ADDED .fossil-settings/ignore-glob Index: .fossil-settings/ignore-glob ================================================================== --- /dev/null +++ .fossil-settings/ignore-glob @@ -0,0 +1,5 @@ +M +MSG* +X.* +_work +modules/tcllibc Index: .github/CONTRIBUTING.md ================================================================== --- .github/CONTRIBUTING.md +++ .github/CONTRIBUTING.md @@ -1,17 +1,17 @@ -Hello. +Hello. __Attention please__ You are currently using the github __mirror__ of the Tcllib sources. -This is __not__ the location where development takes place. +This is __not__ the location where Tcllib 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.tk/tcllib) +[official location of the sources](https://core.tcl-lang.org/tcllib) and enter your ticket into the -[official ticket tracker](https://core.tcl.tk/tcllib/reportlist) +[official ticket tracker](https://core.tcl-lang.org/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. +Hello. __Attention please__ You are currently using the github __mirror__ of the Tcllib sources. -This is __not__ the location where development takes place. +This is __not__ the location where Tcllib 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.tk/tcllib) +[official location of the sources](https://core.tcl-lang.org/tcllib) and enter your ticket into the -[official ticket tracker](https://core.tcl.tk/tcllib/reportlist) +[official ticket tracker](https://core.tcl-lang.org/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. +Hello. __Attention please__ You are currently using the github __mirror__ of the Tcllib sources. -This is __not__ the location where development takes place. +This is __not__ the location where Tcllib 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.tk/tcllib) +[official location of the sources](https://core.tcl-lang.org/tcllib) and enter your ticket into the -[official ticket tracker](https://core.tcl.tk/tcllib/reportlist) +[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist) instead. Thank you for your consideration. DELETED INSTALL.txt Index: INSTALL.txt ================================================================== --- INSTALL.txt +++ /dev/null @@ -1,77 +0,0 @@ -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. DELETED README Index: README ================================================================== --- README +++ /dev/null @@ -1,96 +0,0 @@ -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. DELETED README.developer Index: README.developer ================================================================== --- README.developer +++ /dev/null @@ -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. Index: README.md ================================================================== --- README.md +++ README.md @@ -1,17 +1,44 @@ - -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. +# 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. Please use the -[official ticket tracker](https://core.tcl.tk/tcllib/reportlist) +[official ticket tracker](https://core.tcl-lang.org/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) DELETED README.releasemgr Index: README.releasemgr ================================================================== --- README.releasemgr +++ /dev/null @@ -1,65 +0,0 @@ -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/doctools2base/include/feedback.inc] +[include ../modules/common-text/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/doctools2base/include/feedback.inc] +[include ../modules/common-text/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/doctools2base/include/feedback.inc] +[include ../modules/common-text/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/doctools2base/include/feedback.inc] +[include ../modules/common-text/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/doctools2base/include/feedback.inc] +[include ../modules/common-text/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/doctools2base/include/feedback.inc] +[include ../modules/common-text/feedback.inc] [manpage_end] ADDED devdoc/README.developer Index: devdoc/README.developer ================================================================== --- /dev/null +++ devdoc/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. DELETED devdoc/cvs.branches.fig Index: devdoc/cvs.branches.fig ================================================================== --- devdoc/cvs.branches.fig +++ /dev/null @@ -1,32 +0,0 @@ -#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 DELETED devdoc/devguide.html Index: devdoc/devguide.html ================================================================== --- devdoc/devguide.html +++ /dev/null @@ -1,50 +0,0 @@ - - -

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. -
DELETED devdoc/installation.txt Index: devdoc/installation.txt ================================================================== --- devdoc/installation.txt +++ /dev/null @@ -1,85 +0,0 @@ -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 ADDED devdoc/parts/b_critcl.inc Index: devdoc/parts/b_critcl.inc ================================================================== --- /dev/null +++ devdoc/parts/b_critcl.inc @@ -0,0 +1,38 @@ + +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 installed by +default. + +[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 # This builds the shared library holding + # the accelerators + make install +}] + +[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]. ADDED devdoc/parts/b_tooling.inc Index: devdoc/parts/b_tooling.inc ================================================================== --- /dev/null +++ devdoc/parts/b_tooling.inc @@ -0,0 +1,109 @@ + +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] ADDED devdoc/parts/b_unix.inc Index: devdoc/parts/b_unix.inc ================================================================== --- /dev/null +++ devdoc/parts/b_unix.inc @@ -0,0 +1,22 @@ + +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. ADDED devdoc/parts/b_windows.inc Index: devdoc/parts/b_windows.inc ================================================================== --- /dev/null +++ devdoc/parts/b_windows.inc @@ -0,0 +1,18 @@ + +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. ADDED devdoc/parts/d_bf_branchcmds.inc Index: devdoc/parts/d_bf_branchcmds.inc ================================================================== --- /dev/null +++ devdoc/parts/d_bf_branchcmds.inc @@ -0,0 +1,29 @@ + +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] + ADDED devdoc/parts/d_bf_branches.inc Index: devdoc/parts/d_bf_branches.inc ================================================================== --- /dev/null +++ devdoc/parts/d_bf_branches.inc @@ -0,0 +1,37 @@ + +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. ADDED devdoc/parts/d_bf_dependencies.inc Index: devdoc/parts/d_bf_dependencies.inc ================================================================== --- /dev/null +++ devdoc/parts/d_bf_dependencies.inc @@ -0,0 +1,61 @@ + +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. ADDED devdoc/parts/d_bf_trunk.inc Index: devdoc/parts/d_bf_trunk.inc ================================================================== --- /dev/null +++ devdoc/parts/d_bf_trunk.inc @@ -0,0 +1,30 @@ + +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. ADDED devdoc/parts/d_bf_versions.inc Index: devdoc/parts/d_bf_versions.inc ================================================================== --- /dev/null +++ devdoc/parts/d_bf_versions.inc @@ -0,0 +1,44 @@ +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. ADDED devdoc/parts/d_branchflow.inc Index: devdoc/parts/d_branchflow.inc ================================================================== --- /dev/null +++ devdoc/parts/d_branchflow.inc @@ -0,0 +1,19 @@ +[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] ADDED devdoc/parts/d_contrib.inc Index: devdoc/parts/d_contrib.inc ================================================================== --- /dev/null +++ devdoc/parts/d_contrib.inc @@ -0,0 +1,18 @@ + +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. ADDED devdoc/parts/d_dirlayout.inc Index: devdoc/parts/d_dirlayout.inc ================================================================== --- /dev/null +++ devdoc/parts/d_dirlayout.inc @@ -0,0 +1,149 @@ + +[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] ADDED devdoc/parts/d_documentation.inc Index: devdoc/parts/d_documentation.inc ================================================================== --- /dev/null +++ devdoc/parts/d_documentation.inc @@ -0,0 +1,76 @@ + +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. ADDED devdoc/parts/d_installation.inc Index: devdoc/parts/d_installation.inc ================================================================== --- /dev/null +++ devdoc/parts/d_installation.inc @@ -0,0 +1,94 @@ +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. ADDED devdoc/parts/d_maintain.inc Index: devdoc/parts/d_maintain.inc ================================================================== --- /dev/null +++ devdoc/parts/d_maintain.inc @@ -0,0 +1,71 @@ + +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] ADDED devdoc/parts/d_op_aware.inc Index: devdoc/parts/d_op_aware.inc ================================================================== --- /dev/null +++ devdoc/parts/d_op_aware.inc @@ -0,0 +1,57 @@ + +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] ADDED devdoc/parts/d_op_branch_close.inc Index: devdoc/parts/d_op_branch_close.inc ================================================================== --- /dev/null +++ devdoc/parts/d_op_branch_close.inc @@ -0,0 +1,73 @@ + +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. ADDED devdoc/parts/d_op_branch_import.inc Index: devdoc/parts/d_op_branch_import.inc ================================================================== --- /dev/null +++ devdoc/parts/d_op_branch_import.inc @@ -0,0 +1,32 @@ + +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. ADDED devdoc/parts/d_op_branch_open.inc Index: devdoc/parts/d_op_branch_open.inc ================================================================== --- /dev/null +++ devdoc/parts/d_op_branch_open.inc @@ -0,0 +1,59 @@ + +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. ADDED devdoc/parts/d_op_clean.inc Index: devdoc/parts/d_op_clean.inc ================================================================== --- /dev/null +++ devdoc/parts/d_op_clean.inc @@ -0,0 +1,14 @@ + +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. ADDED devdoc/parts/d_testing.inc Index: devdoc/parts/d_testing.inc ================================================================== --- /dev/null +++ devdoc/parts/d_testing.inc @@ -0,0 +1,90 @@ + +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. ADDED devdoc/parts/d_testwrite.inc Index: devdoc/parts/d_testwrite.inc ================================================================== --- /dev/null +++ devdoc/parts/d_testwrite.inc @@ -0,0 +1,119 @@ + +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. ADDED devdoc/parts/rm_distribute.inc Index: devdoc/parts/rm_distribute.inc ================================================================== --- /dev/null +++ devdoc/parts/rm_distribute.inc @@ -0,0 +1,39 @@ + +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] ADDED devdoc/parts/rm_final.inc Index: devdoc/parts/rm_final.inc ================================================================== --- /dev/null +++ devdoc/parts/rm_final.inc @@ -0,0 +1,1 @@ +todo: finalize release, make candidate official ADDED devdoc/parts/rm_start.inc Index: devdoc/parts/rm_start.inc ================================================================== --- /dev/null +++ devdoc/parts/rm_start.inc @@ -0,0 +1,1 @@ +todo: open a candidate for release ADDED devdoc/parts/rm_tooling.inc Index: devdoc/parts/rm_tooling.inc ================================================================== --- /dev/null +++ devdoc/parts/rm_tooling.inc @@ -0,0 +1,18 @@ + +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]. ADDED devdoc/parts/rm_work.inc Index: devdoc/parts/rm_work.inc ================================================================== --- /dev/null +++ devdoc/parts/rm_work.inc @@ -0,0 +1,7 @@ +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. ADDED devdoc/parts/rq_critcl.inc Index: devdoc/parts/rq_critcl.inc ================================================================== --- /dev/null +++ devdoc/parts/rq_critcl.inc @@ -0,0 +1,35 @@ + +[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. ADDED devdoc/parts/rq_tcl.inc Index: devdoc/parts/rq_tcl.inc ================================================================== --- /dev/null +++ devdoc/parts/rq_tcl.inc @@ -0,0 +1,46 @@ + +[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]. ADDED devdoc/parts/welcome.inc Index: devdoc/parts/welcome.inc ================================================================== --- /dev/null +++ devdoc/parts/welcome.inc @@ -0,0 +1,6 @@ + +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. + DELETED devdoc/releaseguide.html Index: devdoc/releaseguide.html ================================================================== --- devdoc/releaseguide.html +++ /dev/null @@ -1,72 +0,0 @@ - - -

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. -

ADDED devdoc/tcl_community_communication.man Index: devdoc/tcl_community_communication.man ================================================================== --- /dev/null +++ devdoc/tcl_community_communication.man @@ -0,0 +1,178 @@ +[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] ADDED devdoc/tcllib_devguide.man Index: devdoc/tcllib_devguide.man ================================================================== --- /dev/null +++ devdoc/tcllib_devguide.man @@ -0,0 +1,62 @@ +[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] + ADDED devdoc/tcllib_installer.man Index: devdoc/tcllib_installer.man ================================================================== --- /dev/null +++ devdoc/tcllib_installer.man @@ -0,0 +1,90 @@ +[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] + ADDED devdoc/tcllib_license.man Index: devdoc/tcllib_license.man ================================================================== --- /dev/null +++ devdoc/tcllib_license.man @@ -0,0 +1,61 @@ +[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] + ADDED devdoc/tcllib_releasemgr.man Index: devdoc/tcllib_releasemgr.man ================================================================== --- /dev/null +++ devdoc/tcllib_releasemgr.man @@ -0,0 +1,45 @@ +[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] + ADDED devdoc/tcllib_sources.man Index: devdoc/tcllib_sources.man ================================================================== --- /dev/null +++ devdoc/tcllib_sources.man @@ -0,0 +1,69 @@ +[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] Index: embedded/index.md ================================================================== --- embedded/index.md +++ embedded/index.md @@ -1,22 +1,31 @@

Tcl Library Source Code

-Packages -- [Table Of Contents](md/toc.md) -- [Keyword Index](md/index.md) +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/). Index: embedded/md/index.md ================================================================== --- embedded/md/index.md +++ embedded/md/index.md @@ -232,10 +232,12 @@ |/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)| |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)| @@ -344,10 +346,11 @@ |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)| @@ -367,10 +370,11 @@ |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)| @@ -394,14 +398,14 @@ |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) · [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) · [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) · [tool](tcllib/files/modules/httpd/httpd\.md) · [uri](tcllib/files/modules/uri/uri\.md) · [websocket](tcllib/files/modules/websocket/websocket\.md)| -|httpd|[tool](tcllib/files/modules/httpd/httpd\.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|[tool](tcllib/files/modules/httpd/httpd\.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)| @@ -531,11 +535,11 @@ |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::statistics](tcllib/files/modules/math/statistics\.md)| +|mathematics|[math::fourier](tcllib/files/modules/math/fourier\.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)| @@ -612,10 +616,11 @@ |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)| |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)| @@ -639,11 +644,11 @@ |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)| +|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)| @@ -685,10 +690,11 @@ #### 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 @@ -797,11 +803,11 @@ |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) · [smtpd](tcllib/files/modules/smtpd/smtpd\.md) · [tool](tcllib/files/modules/httpd/httpd\.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)| @@ -873,11 +879,11 @@ |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|[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/httpd/httpd\.md) · [tool](tcllib/files/modules/tool/tool\.md) · [tool::dict\_ensemble](tcllib/files/modules/tool/tool\_dict\_ensemble\.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)| @@ -944,10 +950,11 @@ |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)| @@ -983,11 +990,11 @@ |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|[tool](tcllib/files/modules/httpd/httpd\.md)| +|WWW|[httpd](tcllib/files/modules/httpd/httpd\.md)| |www|[uri](tcllib/files/modules/uri/uri\.md)| #### Keywords: X Index: embedded/md/tcllib/files/apps/dtplite.md ================================================================== --- embedded/md/tcllib/files/apps/dtplite.md +++ embedded/md/tcllib/files/apps/dtplite.md @@ -322,14 +322,14 @@ 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 + toc.html + index.html files/ - path/to/FOO\.html + path/to/FOO.html The last line in the example shows the document generated for a file FOO located at inputdirectory/path/to/FOO @@ -338,23 +338,23 @@ 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 + .toc + .idx + .tocdoc + .idxdoc + .xrf + toc.html + index.html FOO1/ - \.\.\. + ... FOO2/ - toc\.html + toc.html files/ - path/to/BAR\.html + 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\. Index: embedded/md/tcllib/files/apps/page.md ================================================================== --- embedded/md/tcllib/files/apps/page.md +++ embedded/md/tcllib/files/apps/page.md @@ -123,11 +123,11 @@ 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 + -c peg And now the recognized options and their arguments, if they have any: - __\-\-help__ @@ -264,16 +264,16 @@ 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 + --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*"\. Index: embedded/md/tcllib/files/apps/pt.md ================================================================== --- embedded/md/tcllib/files/apps/pt.md +++ embedded/md/tcllib/files/apps/pt.md @@ -675,64 +675,64 @@ 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 ; + 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 + 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 channel [open $input r] - set parser \[calculator\] - set ast \[$parser parse $channel\] + set parser [calculator] + set ast [$parser parse $channel] $parser destroy close $channel - \.\.\. now process the returned abstract syntax tree \.\.\. + ... 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\} - \} - \} - \} - \} + 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 + 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\. ADDED embedded/md/tcllib/files/devdoc/tcl_community_communication.md Index: embedded/md/tcllib/files/devdoc/tcl_community_communication.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/devdoc/tcl_community_communication.md @@ -0,0 +1,196 @@ + +[//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 ADDED embedded/md/tcllib/files/devdoc/tcllib_devguide.md Index: embedded/md/tcllib/files/devdoc/tcllib_devguide.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/devdoc/tcllib_devguide.md @@ -0,0 +1,1046 @@ + +[//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\. ADDED embedded/md/tcllib/files/devdoc/tcllib_installer.md Index: embedded/md/tcllib/files/devdoc/tcllib_installer.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/devdoc/tcllib_installer.md @@ -0,0 +1,339 @@ + +[//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 installed +by default\. + +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 # This builds the shared library holding + # the accelerators + make install + +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\. ADDED embedded/md/tcllib/files/devdoc/tcllib_license.md Index: embedded/md/tcllib/files/devdoc/tcllib_license.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/devdoc/tcllib_license.md @@ -0,0 +1,69 @@ + +[//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\. ADDED embedded/md/tcllib/files/devdoc/tcllib_releasemgr.md Index: embedded/md/tcllib/files/devdoc/tcllib_releasemgr.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/devdoc/tcllib_releasemgr.md @@ -0,0 +1,124 @@ + +[//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\. ADDED embedded/md/tcllib/files/devdoc/tcllib_sources.md Index: embedded/md/tcllib/files/devdoc/tcllib_sources.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/devdoc/tcllib_sources.md @@ -0,0 +1,85 @@ + +[//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\. 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,11 +1,11 @@ [//000000001]: # (aes \- Advanced Encryption Standard \(AES\)) [//000000002]: # (Generated from file 'aes\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005, Pat Thoyts -Copyright © 2012\-2014, Andreas Kupries ) -[//000000004]: # (aes\(n\) 1\.2\.1 tcllib "Advanced Encryption Standard \(AES\)") +[//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 | EXAMPLES - % set nil\_block \[string repeat \\\\0 16\] - % aes::aes \-hex \-mode cbc \-dir encrypt \-key $nil\_block $nil\_block + % 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\] + 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 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 @@ -1136,11 +1136,11 @@ 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 + 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 @@ -1426,22 +1426,22 @@ # 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 + 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 + 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\. @@ -1479,13 +1479,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... 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 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 @@ -141,11 +141,11 @@ 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::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 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,12 +1,12 @@ [//000000001]: # (asn \- ASN\.1 processing) [//000000002]: # (Generated from file 'asn\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Andreas Kupries -Copyright © 2004 Jochen Loewer -Copyright © 2004\-2011 Michael Schlenker ) -[//000000004]: # (asn\(n\) 0\.8 tcllib "ASN\.1 processing") +[//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 | 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\]\] + 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) 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,11 +1,11 @@ [//000000001]: # (base64 \- Text encoding & decoding binary data) [//000000002]: # (Generated from file 'base64\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2000, Eric Melski -Copyright © 2001, Miguel Sofer) -[//000000004]: # (base64\(n\) 2\.4\.2 tcllib "Text encoding & decoding binary data") +[//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 | EXAMPLES % base64::encode "Hello, world" SGVsbG8sIHdvcmxk - % base64::encode \[string repeat xyz 20\] + % base64::encode [string repeat xyz 20] eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6 eHl6eHl6eHl6 - % base64::encode \-wrapchar "" \[string repeat xyz 20\] + % 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\]\] + # 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 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 @@ -92,24 +92,24 @@ 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 + % set d [uuencode::encode "Hello World!"] + 2&5L;&\\@5V]R;&0A % uuencode::uudecode $d - Hello World\! + Hello World! - % set d \[uuencode::uuencode \-name hello\.txt "Hello World"\] - begin 644 hello\.txt - \+2&5L;&\\@5V\]R;&0\` - \` + % 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\}\} + {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 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 @@ -97,13 +97,13 @@ 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\- + % 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) 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 @@ -57,13 +57,13 @@ ## Basics One of the most simplest benchmarks which can be written in bench is - bench \-desc LABEL \-body \{ + 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\. @@ -78,17 +78,17 @@ 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 - \} +> 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 @@ -129,18 +129,18 @@ 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 - \} +> 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 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 @@ -143,16 +143,16 @@ 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\!" + % 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\] + 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, ADDED embedded/md/tcllib/files/modules/clay/clay.md Index: embedded/md/tcllib/files/modules/clay/clay.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/clay/clay.md @@ -0,0 +1,807 @@ + +[//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 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 @@ -158,47 +158,47 @@ __::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\] - \} 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\! + 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\} \{ - \.\.\. - \} + } + + 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 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,12 +1,12 @@ [//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\. -Copyright © 2003\-2004 ActiveState Corporation\. -Copyright © 2006\-2009 Andreas Kupries ) -[//000000004]: # (comm\(n\) 4\.6\.3 tcllib "Remote communication") +[//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 | Commands @@ -174,14 +174,14 @@ 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" + % ::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\. @@ -203,15 +203,15 @@ 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" + "-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" + "::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\. @@ -391,15 +391,15 @@ 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\]\} \{ + % ::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__ @@ -422,15 +422,15 @@ 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\]\} \{ + ::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__\. @@ -453,61 +453,61 @@ Examples: 1. augmenting a command - % ::comm::comm send \[::comm::comm self\] pid + % ::comm::comm send [::comm::comm self] pid 5013 - % ::comm::comm hook eval \{puts "going to execute $buffer"\} - % ::comm::comm send \[::comm::comm self\] pid + % ::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 + % ::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\} + % ::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 + % ::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\]\} + % ::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 + % ::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\(\)__\. @@ -548,17 +548,17 @@ 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 \{ + ::comm::comm hook lost { global myvar - if \{$myvar\(id\) == $id\} \{ + if {$myvar(id) == $id} { myfunc return - \} - \} + } + } ## Unsupported These interfaces may change or go away in subsequence releases\. @@ -573,20 +573,20 @@ 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\} \{ + 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\] - \} + } + 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 @@ -595,17 +595,17 @@ 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 + # Load and initialize tls package require tls - tls::init \-cafile /path/to/ca/cert \-keyfile \.\.\. + tls::init -cafile /path/to/ca/cert -keyfile ... - \# Create secured comm channel - ::comm::comm new SECURE \-socketcmd tls::socket \-listen 1 - \.\.\. + # 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\. @@ -689,32 +689,32 @@ 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\. + # 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*? @@ -904,11 +904,11 @@ __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\} + 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 @@ -986,13 +986,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... your own application code ... # Author John LoVerso, John@LoVerso\.Southborough\.MA\.US 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 @@ -126,29 +126,29 @@ 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\}\}\} + (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 + 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\} + (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\] + 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\. @@ -173,12 +173,12 @@ __[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\}\}\} + {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 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 @@ -113,13 +113,13 @@ % 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\} + % one::assert {1 == 0} assertion failed: 1 == 0 - % two::assert \{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 @@ -148,12 +148,12 @@ 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\} + % proc a {} {while 1 {return -code error a}} + % proc b {} {control::do {return -code error b} while 1} % catch a 1 % catch b 0 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 @@ -113,22 +113,22 @@ Once this command completes the token will be invalid\. The result is a 32 bit integer value\. # EXAMPLES - % crc::cksum "Hello, World\!" + % crc::cksum "Hello, World!" 2609532967 - % crc::cksum \-format 0x%X "Hello, World\!" + % crc::cksum -format 0x%X "Hello, World!" 0x9B8A5027 - % crc::cksum \-file cksum\.tcl + % crc::cksum -file cksum.tcl 1828321145 - % set tok \[crc::CksumInit\] + % set tok [crc::CksumInit] % crc::CksumUpdate $tok "Hello, " - % crc::CksumUpdate $tok "World\!" + % crc::CksumUpdate $tok "World!" % crc::CksumFinal $tok 2609532967 # AUTHORS 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 @@ -128,20 +128,20 @@ option if this marker is not included\. Always use the *\-\-* option termination flag before giving the data argument\. # EXAMPLES - % crc::crc16 \-\- "Hello, World\!" + % crc::crc16 -- "Hello, World!" 64077 - % crc::crc\-ccitt \-\- "Hello, World\!" + % crc::crc-ccitt -- "Hello, World!" 26586 - % crc::crc16 \-format 0x%X \-\- "Hello, World\!" + % crc::crc16 -format 0x%X -- "Hello, World!" 0xFA4D - % crc::crc16 \-file crc16\.tcl + % crc::crc16 -file crc16.tcl 51675 # AUTHORS Pat Thoyts 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 @@ -127,22 +127,22 @@ Once this command completes the token will be invalid\. The result is a 32 bit integer value\. # EXAMPLES - % crc::crc32 "Hello, World\!" + % crc::crc32 "Hello, World!" 3964322768 - % crc::crc32 \-format 0x%X "Hello, World\!" + % crc::crc32 -format 0x%X "Hello, World!" 0xEC4AC3D0 - % crc::crc32 \-file crc32\.tcl + % crc::crc32 -file crc32.tcl 483919716 - % set tok \[crc::Crc32Init\] + % set tok [crc::Crc32Init] % crc::Crc32Update $tok "Hello, " - % crc::Crc32Update $tok "World\!" + % crc::Crc32Update $tok "World!" % crc::Crc32Final $tok 3964322768 # AUTHORS 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 @@ -96,17 +96,17 @@ Return the checksum using an alternative format template\. # EXAMPLES - % crc::sum "Hello, World\!" + % crc::sum "Hello, World!" 37287 - % crc::sum \-format 0x%X "Hello, World\!" + % crc::sum -format 0x%X "Hello, World!" 0x91A7 - % crc::sum \-file sum\.tcl + % crc::sum -file sum.tcl 13392 # AUTHORS Pat Thoyts 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 @@ -81,30 +81,30 @@ 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::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::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::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 @@ -129,12 +129,12 @@ 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 eventid [incr ::cron::eventcount] + set var ::cron::event_#$eventid set $var 0 ::after $ms "set $var 1" ::vwait $var ::unset $var @@ -196,11 +196,11 @@ - __::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\} + ::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* 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 @@ -216,25 +216,25 @@ # EXAMPLE Using the regular format the record - 123,"123,521\.2","Mary says ""Hello, I am Mary""","" + 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\) " + 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\) + 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 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,11 +1,11 @@ [//000000001]: # (debug \- debug narrative) [//000000002]: # (Generated from file 'debug\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 200?, Colin McCormack, Wub Server Utilities -Copyright © 2012\-2014, Andreas Kupries ) -[//000000004]: # (debug\(n\) 1\.0\.6 tcllib "debug narrative") +[//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 | ) -[//000000004]: # (debug::heartbeat\(n\) 1 tcllib "debug narrative") +[//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 | SYNOPSIS package require Tcl 8\.5 -package require debug::heartbeat ?1? +package require debug::heartbeat ?1\.0\.1? package require debug ?1? [__[debug](debug\.md)__ __heartbeat__ ?*delta*?](#1) # DESCRIPTION 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,11 +1,11 @@ [//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 -Copyright © 2012, Andreas Kupries ) -[//000000004]: # (debug::timestamp\(n\) 1 tcllib "debug narrative") +[//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 | EXAMPLES package require defer 1 - apply \{\{\} \{ - set fd \[open /dev/null\] + apply {{} { + set fd [open /dev/null] defer::defer close $fd - \}\} + }} # REFERENCES # AUTHORS 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 @@ -169,19 +169,19 @@ 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 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"\] + 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\] + set plaintext [DES::Decrypt $Key $ciphertext] DES::Final $Key # REFERENCES 1. "Data Encryption Standard", Federal Information Processing Standards 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 @@ -32,10 +32,11 @@ - [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) @@ -55,12 +56,12 @@ 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*\. + 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\. @@ -81,30 +82,30 @@ 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\] + 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 \{ + option { + color { default: blue - \} - fruit \{ + } + fruit { widget: select - values: \{mango apple cherry grape\} - \} - \} + 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 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,10 +1,10 @@ [//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\.4\.0 tcllib "Domain Name Service") +[//000000004]: # (dns\(n\) 1\.4\.1 tcllib "Domain Name Service")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.2 -package require dns ?1\.4\.0? +package require dns ?1\.4\.1? [__::dns::resolve__ *query* ?*options*?](#1) [__::dns::configure__ ?*options*?](#2) [__::dns::name__ *token*](#3) [__::dns::address__ *token*](#4) @@ -251,41 +251,41 @@ 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\] + % set tok [dns::resolve www.tcl.tk] ::dns::1 % dns::status $tok ok % dns::address $tok - 199\.175\.6\.239 + 199.175.6.239 % dns::name $tok - www\.tcl\.tk + 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"\] + % 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\] + % 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\] + % 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 + 104.25.119.118 104.25.120.118 # REFERENCES 1. Mockapetris, P\., "Domain Names \- Concepts and Facilities", RFC 1034, November 1987\. 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,11 +1,11 @@ [//000000001]: # (tcllib\_ip \- Domain Name Service) [//000000002]: # (Generated from file 'tcllib\_ip\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004, Pat Thoyts -Copyright © 2005 Aamer Akhter ) -[//000000004]: # (tcllib\_ip\(n\) 1\.4 tcllib "Domain Name Service") +[//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 | __::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 + % ::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::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 @@ -147,11 +147,11 @@ 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 + % 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 @@ -167,33 +167,33 @@ 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::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 + 255.255.255.255 - __::ip::toInteger__ *ipaddr* This command converts a dotted form ip into an integer number\. - % ::ip::toInteger 1\.1\.1\.0 + % ::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 + % ::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 @@ -206,33 +206,33 @@ 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 1.1.1.0/24 + 1.1.1.255 - ::ip::broadcastAddress \{0x01010100 0xffffff00\} + ::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 + ::ip::maskToLength 0xffffff00 -ipv4 24 - % ::ip::maskToLength 255\.255\.255\.0 + % ::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 + 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__\. @@ -248,14 +248,14 @@ 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 + % ::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 + ::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 @@ -283,55 +283,55 @@ * \-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\}\} + % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff}} 0 - % ::ip::isOverlapNative 0x01010100 0xffffff00 \{\{0x02010001 0xffffffff\} \{0x01010101 0xffffffff\}\} + % ::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::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.5/24 + 1.1.1.1 - %::ip::ipHostFromPrefix 1\.1\.1\.1/32 - 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::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::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 @@ -340,12 +340,12 @@ 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::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 @@ -355,24 +355,24 @@ # EXAMPLES % ip::version ::1 6 - % ip::version 127\.0\.0\.1 + % ip::version 127.0.0.1 4 % ip::normalize 127/8 - 127\.0\.0\.0/8 - % ip::contract 192\.168\.0\.0 - 192\.168 + 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 + % ip::equal 192.168.0.4/16 192.168.0.0/16 1 % ip::equal fec0::1/10 fec0::fe01/10 1 # REFERENCES 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 @@ -107,29 +107,29 @@ 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\] \{\} + 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 + 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 @@ -151,17 +151,17 @@ '%' '<' 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 \} + 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 @@ -173,53 +173,53 @@ 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\] + 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 + 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 '%<\-' @@ -230,78 +230,78 @@ 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 \{\#\}\] + 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 + 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 \{\}\] + 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 + 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 @@ -393,18 +393,18 @@ 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 +>    % \\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 — 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 @@ -112,69 +112,69 @@ 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\} + % \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\} + % \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\} + % \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|able extension + % \begin{tcl} + %<*load> + load [file rootname [info script]][info sharedlibextension] % - %<\*\!load> - \# \.\.\. even more clever scripted counterpart of the extension - \# also elided \.\.\. - % - \} + %<*!load> + # ... even more clever scripted counterpart of the extension + # also elided ... + % + } % - % \\end\{tcl\} - % and that's it\! + % \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\} + % \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\} + % \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\} + % \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|able extension + % \begin{tcl} + %<*load> + load [file rootname [info script]][info sharedlibextension] % - %<\*\!load> - \# \.\.\. even more clever scripted counterpart of the extension - \# also elided \.\.\. - % - \} + %<*!load> + # ... even more clever scripted counterpart of the extension + # also elided ... + % + } % - % \\end\{tcl\} - % and that's it\! + % \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 @@ -321,45 +321,45 @@ - __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 + ## + ## 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\} + 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'\. + ## 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\} + 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*? @@ -385,11 +385,11 @@ 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\]\] + $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 @@ -432,40 +432,40 @@ 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\. + % [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 + % 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\. + % [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 - %<\!tcl83> return $a - \} - % \[list\_end\] + % return $a + } + % [list_end] % - % \[manpage\_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\. @@ -601,17 +601,17 @@ __[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 + 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"\. 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 @@ -65,24 +65,24 @@ 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 \.\.\.\} + { + { + {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 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 @@ -59,60 +59,60 @@ 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\}\] \.\.\. + ... [key {markup language}] ... - \.\.\. \[manpage thefile \\\\ - \{file description\}\] \.\.\. + ... [manpage thefile \ + {file description}] ... ## Basic structure The most simple document which can be written in docidx is - \[index\_begin GROUPTITLE TITLE\] - \[index\_end\] + [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\] +> \[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\] +> \[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\. @@ -132,24 +132,24 @@ 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\] +> \[__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\] +> \[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 @@ -164,15 +164,15 @@ 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\. - \.\.\. +>   \.\.\. +>   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 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 @@ -87,20 +87,20 @@ 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 + 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 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 @@ -217,28 +217,28 @@ 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 - \.\.\. + 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\. 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 @@ -63,21 +63,21 @@ 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\}\] \.\.\. + ... [division_start {Appendix 1}] ... - \.\.\. \[item thefile \\\\ - label \{file description\}\] \.\.\. + ... [item thefile \ + label {file description}] ... ## Basic structure The most simple document which can be written in doctoc is - \[toc\_begin GROUPTITLE TITLE\] - \[toc\_end\] + [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 @@ -100,17 +100,17 @@ 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\] +> \[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 @@ -139,62 +139,62 @@ 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\] +> \[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\] +> \[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\] +> \[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\. @@ -202,24 +202,24 @@ 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\] +> \[__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\] +> \[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 @@ -234,15 +234,15 @@ 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\. - \.\.\. +>   \.\.\. +>   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 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 @@ -87,23 +87,23 @@ 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 + 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 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 @@ -216,28 +216,28 @@ 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 - \.\.\. + 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\. 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,10 +1,10 @@ [//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\.1 tcllib "Documentation tools") +[//000000004]: # (doctools\(n\) 1\.5\.6 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.2 -package require doctools ?1\.5\.1? +package require doctools ?1\.5\.6? [__::doctools::new__ *objectName* ?*option value*\.\.\.?](#1) [__::doctools::help__](#2) [__::doctools::search__ *path*](#3) [__objectName__ __method__ ?*arg arg \.\.\.*?](#4) 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 @@ -68,38 +68,38 @@ 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\]"\] \.\.\. + ... [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\] + [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 @@ -130,45 +130,45 @@ 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\] +> \[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 \.\./doctools2base/include/feedback\.inc\] - \[manpage\_end\] + [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 \{ \.\.\. \}__\] +> \[__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 @@ -176,25 +176,25 @@ 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\] +> \[__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\] +> \[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 @@ -215,18 +215,18 @@ 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\] +> \[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 @@ -237,20 +237,20 @@ 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\] +> \[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 @@ -258,24 +258,24 @@ 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\] +> \[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\. @@ -377,18 +377,18 @@ 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\. - \.\.\. +>   \.\.\. +>   \[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 @@ -398,15 +398,15 @@ 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\. - \.\.\. +>   \.\.\. +>   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 @@ -434,18 +434,18 @@ 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\] +>   \.\.\. +>   \[__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 @@ -461,19 +461,19 @@ \(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\] \.\.\. - \}\] +> \[__example__ \{ +>     \.\.\. \[list\_begin enumerated\] \.\.\. +>   \}\] Using __example\_begin__ / __example\_end__ this would look like - \[__example\_begin__\] - \.\.\. \[list\_begin enumerated\] \.\.\. - \[__example\_end__\] +> \[__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 @@ -532,46 +532,46 @@ 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__\] - \.\.\. +>   \.\.\. +>   \[__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\] - \.\.\. +>   \.\.\. +>   \[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 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 @@ -91,56 +91,56 @@ __list\_begin__ with __X__ as its type argument\. The syntax: manpage = defs - MANPAGE\_BEGIN + 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 \} + 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 + 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 \} + | 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 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 @@ -283,28 +283,28 @@ 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 - \.\.\. + 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\. 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,11 +1,11 @@ [//000000001]: # (mpexpand \- Documentation toolbox) [//000000002]: # (Generated from file 'mpexpand\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002 Andreas Kupries -Copyright © 2003 Andreas Kupries ) -[//000000004]: # (mpexpand\(n\) 1\.0 tcllib "Documentation toolbox") +[//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 | ) -[//000000004]: # (doctools::idx::export::docidx\(n\) 0\.1 tcllib "Documentation tools") +[//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 | SYNOPSIS package require Tcl 8\.4 -package require doctools::idx::export::docidx ?0\.1? +package require doctools::idx::export::docidx ?0\.2\.1? [__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) # DESCRIPTION @@ -248,6 +248,6 @@ Text formatter plugin # COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,10 +1,10 @@ [//000000001]: # (doctools::idx::export \- Documentation tools) [//000000002]: # (Generated from file 'idx\_export\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2018 Andreas Kupries ) -[//000000004]: # (doctools::idx::export\(n\) 0\.2 tcllib "Documentation tools") +[//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 | SYNOPSIS -package require doctools::idx::export ?0\.2? +package require doctools::idx::export ?0\.2\.1? package require Tcl 8\.4 -package require doctools::config +package require struct::map package require doctools::idx::structure package require snit package require pluginmgr [__::doctools::idx::export__ *objectName*](#1) @@ -467,6 +467,6 @@ Documentation tools # COPYRIGHT -Copyright © 2009\-2018 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,9 +1,9 @@ [//000000001]: # (doctools::idx::export::html \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) +[//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 | COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,9 +1,9 @@ [//000000001]: # (doctools::idx::export::json \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) [//000000004]: # (doctools::idx::export::json\(n\) 0\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Configuration The JSON export plugin recognizes the following configuration variables and changes its behaviour as they specify\. @@ -255,6 +255,6 @@ Text formatter plugin # COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,9 +1,9 @@ [//000000001]: # (doctools::idx::export::nroff \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) [//000000004]: # (doctools::idx::export::nroff\(n\) 0\.3 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,9 +1,9 @@ [//000000001]: # (doctools::idx::export::text \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) [//000000004]: # (doctools::idx::export::text\(n\) 0\.2 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,9 +1,9 @@ [//000000001]: # (doctools::idx::export::wiki \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) [//000000004]: # (doctools::idx::export::wiki\(n\) 0\.2 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,10 +1,10 @@ [//000000001]: # (doctools::idx::import \- Documentation tools) [//000000002]: # (Generated from file 'idx\_import\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2018 Andreas Kupries ) -[//000000004]: # (doctools::idx::import\(n\) 0\.2 tcllib "Documentation tools") +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) +[//000000004]: # (doctools::idx::import\(n\) 0\.2\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS -package require doctools::idx::import ?0\.2? +package require doctools::idx::import ?0\.2\.1? package require Tcl 8\.4 -package require doctools::config +package require struct::map package require doctools::idx::structure package require snit package require pluginmgr [__::doctools::idx::import__ *objectName*](#1) @@ -524,6 +524,6 @@ Documentation tools # COPYRIGHT -Copyright © 2009\-2018 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,10 +1,10 @@ [//000000001]: # (doctools::idx::import::json \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (doctools::idx::import::json\(n\) 0\.1 tcllib "Documentation tools") +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) +[//000000004]: # (doctools::idx::import::json\(n\) 0\.2\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS -package require Tcl 8\.4 -package require doctools::idx::import::json ?0\.1? +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) @@ -77,51 +77,51 @@ 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 \{\} - \} + 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" : \{ + { + "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"\] - \}, + "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\. @@ -227,6 +227,6 @@ Text formatter plugin # COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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 @@ -128,39 +128,39 @@ 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::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::<\*> + | | + doctools::text doctools::nroff::man_macros = + | + doctools::msgcat::idx::<*> c, en, de, fr - \(fr == en for now\) + (fr == en for now) ~~ Interoperable objects, without actual package dependencies - \-\- Package dependency, higher requires lower package + -- Package dependency, higher requires lower package = Dynamic dependency through plugin system - <\*> Multiple packages following the given form of naming\. + <*> 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 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,10 +1,10 @@ [//000000001]: # (doctools::idx::import::docidx \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (doctools::idx::import::docidx\(n\) 0\.1 tcllib "Documentation tools") +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) +[//000000004]: # (doctools::idx::import::docidx\(n\) 0\.2\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS -package require Tcl 8\.4 -package require doctools::idx::import::docidx ?0\.1? +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 @@ -206,6 +206,6 @@ Text formatter plugin # COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,10 +1,10 @@ [//000000001]: # (doctools::toc::export::doctoc \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (doctools::toc::export::doctoc\(n\) 0\.1 tcllib "Documentation tools") +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) +[//000000004]: # (doctools::toc::export::doctoc\(n\) 0\.2\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.4 -package require doctools::toc::export::doctoc ?0\.1? +package require doctools::toc::export::doctoc ?0\.2\.1? [__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) # DESCRIPTION @@ -276,6 +276,6 @@ Text formatter plugin # COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,10 +1,10 @@ [//000000001]: # (doctools::toc::import::doctoc \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (doctools::toc::import::doctoc\(n\) 0\.1 tcllib "Documentation tools") +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) +[//000000004]: # (doctools::toc::import::doctoc\(n\) 0\.2\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS -package require Tcl 8\.4 -package require doctools::toc::import::doctoc ?0\.1? +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 @@ -235,6 +235,6 @@ Text formatter plugin # COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,10 +1,10 @@ [//000000001]: # (doctools::toc::export \- Documentation tools) [//000000002]: # (Generated from file 'toc\_export\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2018 Andreas Kupries ) -[//000000004]: # (doctools::toc::export\(n\) 0\.2 tcllib "Documentation tools") +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) +[//000000004]: # (doctools::toc::export\(n\) 0\.2\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS -package require doctools::toc::export ?0\.2? +package require doctools::toc::export ?0\.2\.1? package require Tcl 8\.4 -package require doctools::config +package require struct::map package require doctools::toc::structure package require snit package require pluginmgr [__::doctools::toc::export__ *objectName*](#1) @@ -481,6 +481,6 @@ Documentation tools # COPYRIGHT -Copyright © 2009\-2018 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,9 +1,9 @@ [//000000001]: # (doctools::toc::export::html \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) [//000000004]: # (doctools::toc::export::html\(n\) 0\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,9 +1,9 @@ [//000000001]: # (doctools::toc::export::json \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) [//000000004]: # (doctools::toc::export::json\(n\) 0\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Configuration The JSON export plugin recognizes the following configuration variables and changes its behaviour as they specify\. @@ -304,6 +304,6 @@ Text formatter plugin # COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,9 +1,9 @@ [//000000001]: # (doctools::toc::export::nroff \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) [//000000004]: # (doctools::toc::export::nroff\(n\) 0\.2 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,9 +1,9 @@ [//000000001]: # (doctools::toc::export::text \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) [//000000004]: # (doctools::toc::export::text\(n\) 0\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,9 +1,9 @@ [//000000001]: # (doctools::toc::export::wiki \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) [//000000004]: # (doctools::toc::export::wiki\(n\) 0\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,10 +1,10 @@ [//000000001]: # (doctools::toc::import \- Documentation tools) [//000000002]: # (Generated from file 'toc\_import\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2018 Andreas Kupries ) -[//000000004]: # (doctools::toc::import\(n\) 0\.2 tcllib "Documentation tools") +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) +[//000000004]: # (doctools::toc::import\(n\) 0\.2\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS -package require doctools::toc::import ?0\.2? +package require doctools::toc::import ?0\.2\.1? package require Tcl 8\.4 -package require doctools::config +package require struct::map package require doctools::toc::structure package require snit package require pluginmgr [__::doctools::toc::import__ *objectName*](#1) @@ -541,6 +541,6 @@ Documentation tools # COPYRIGHT -Copyright © 2009\-2018 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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,10 +1,10 @@ [//000000001]: # (doctools::toc::import::json \- Documentation tools) [//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (doctools::toc::import::json\(n\) 0\.1 tcllib "Documentation tools") +[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) +[//000000004]: # (doctools::toc::import::json\(n\) 0\.2\.1 tcllib "Documentation tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS -package require Tcl 8\.4 -package require doctools::toc::import::json ?0\.1? +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) @@ -77,71 +77,71 @@ 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 + 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 + }} + {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 + }} + {reference { + desc {Parsing text in doctoc format} + id parse.man label doctools::toc::parse - \}\} - \} + }} + } label Processing - \}\} - \} - label \{Table of Contents\} + }} + } + label {Table of Contents} title TOC - \} + } is equivalent to the JSON string - \{ - "doctools::toc" : \{ - "items" : \[\{ - "reference" : \{ - "desc" : "DocTools \- Tables of Contents", - "id" : "introduction\.man", + { + "doctools::toc" : { + "items" : [{ + "reference" : { + "desc" : "DocTools - Tables of Contents", + "id" : "introduction.man", "label" : "doctools::toc::introduction" - \} - \},\{ - "division" : \{ - "id" : "processing\.man", - "items" : \[\{ - "reference" : \{ + } + },{ + "division" : { + "id" : "processing.man", + "items" : [{ + "reference" : { "desc" : "doctoc serialization utilities", - "id" : "structure\.man", + "id" : "structure.man", "label" : "doctools::toc::structure" - \} - \},\{ - "reference" : \{ + } + },{ + "reference" : { "desc" : "Parsing text in doctoc format", - "id" : "parse\.man", + "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\. @@ -276,6 +276,6 @@ Text formatter plugin # COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009\-2019 Andreas Kupries 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 @@ -128,39 +128,39 @@ 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::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::<\*> + | | + doctools::text doctools::nroff::man_macros = + | + doctools::msgcat::toc::<*> c, en, de, fr - \(fr == en for now\) + (fr == en for now) ~~ Interoperable objects, without actual package dependencies - \-\- Package dependency, higher requires lower package + -- Package dependency, higher requires lower package = Dynamic dependency through plugin system - <\*> Multiple packages following the given form of naming\. + <*> 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 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 @@ -324,14 +324,14 @@ 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 + toc.html + index.html files/ - path/to/FOO\.html + path/to/FOO.html The last line in the example shows the document generated for a file FOO located at inputdirectory/path/to/FOO @@ -340,23 +340,23 @@ 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 + .toc + .idx + .tocdoc + .idxdoc + .xrf + toc.html + index.html FOO1/ - \.\.\. + ... FOO2/ - toc\.html + toc.html files/ - path/to/BAR\.html + 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\. 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 @@ -74,14 +74,14 @@ returns the changed path as its result\. Symbolic links in the path are *not* resolved\. Examples: - fileutil::lexnormalize /foo/\./bar + fileutil::lexnormalize /foo/./bar => /foo/bar - fileutil::lexnormalize /foo/\.\./bar + fileutil::lexnormalize /foo/../bar => /bar - __::fileutil::fullnormalize__ *path* This command resolves all symbolic links in the *path* and returns the @@ -250,14 +250,14 @@ 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 + # find .tcl files package require fileutil - proc is\_tcl \{name\} \{return \[string match \*\.tcl $name\]\} - set tcl\_files \[fileutil::find \. is\_tcl\] + 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 @@ -478,40 +478,40 @@ 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/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/tty0/subsystem --> ../../class/tty /sys/dev/tty1/bus - /sys/dev/tty1/subsystem \-\-> \.\./\.\./class/tty + /sys/dev/tty1/subsystem --> ../../class/tty /sys/dev/tty2/bus - /sys/dev/tty2/subsystem \-\-> \.\./\.\./class/tty + /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\]\} \{ + proc NoLinks {fileName} { + if {[string equal [file type $fileName] link]} { return 0 - \} + } return 1 - \} + } - fileutil::traverse T /sys/devices \-prefilter NoLinks - T foreach p \{ + 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 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 @@ -400,45 +400,45 @@ # 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 \\\\ + $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 \* + $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__, @@ -446,18 +446,18 @@ __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 + $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 ADDED embedded/md/tcllib/files/modules/fileutil/paths.md Index: embedded/md/tcllib/files/modules/fileutil/paths.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/fileutil/paths.md @@ -0,0 +1,100 @@ + +[//000000001]: # (fileutil::paths \- ) +[//000000002]: # (Generated from file 'paths\.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (fileutil::paths\(n\) 1 tcllib "") + +
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
+ +# NAME + +fileutil::paths \- Manage search path pools + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + +# 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) + +# 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 *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: + + - *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](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas +for enhancements you may have for either package and/or documentation\. + +When proposing code changes, please provide *unified diffs*, i\.e the output of +__diff \-u__\. + +Note further that *attachments* are strongly preferred over inlined patches\. +Attachments can be made by 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: embedded/md/tcllib/files/modules/fileutil/traverse.md ================================================================== --- embedded/md/tcllib/files/modules/fileutil/traverse.md +++ embedded/md/tcllib/files/modules/fileutil/traverse.md @@ -152,38 +152,38 @@ 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/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/tty0/subsystem --> ../../class/tty /sys/dev/tty1/bus - /sys/dev/tty1/subsystem \-\-> \.\./\.\./class/tty + /sys/dev/tty1/subsystem --> ../../class/tty /sys/dev/tty2/bus - /sys/dev/tty2/subsystem \-\-> \.\./\.\./class/tty + /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\]\} \{ + proc NoLinks {fileName} { + if {[string equal [file type $fileName] link]} { return 0 - \} + } return 1 - \} + } - fileutil::traverse T /sys/devices \-prefilter NoLinks - T foreach p \{ + 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 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 @@ -169,11 +169,11 @@ 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 - + The special comparison operator __x__ signals that no comparison should be done, or, in other words, that the fetched value will always match *val*\. 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 @@ -111,16 +111,16 @@ 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\] \{ + 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 @@ -127,16 +127,16 @@ 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 \} - \} + generator define nats {} { + while 1 { generator yield [incr nat] } + } + generator foreach n [nats] { + if {$n > 100} { break } + } # COMMANDS - __generator__ __define__ *name* *params* *body* @@ -220,34 +220,34 @@ 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 define lines file { + set in [open $file] + # Ensure file is always closed generator finally close $in - while \{\[gets $in line\] >= 0\} \{ + 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 + } + } + 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 define map {f xs} { generator finally generator destroy $xs - generator foreach x $xs \{ generator yield \[\{\*\}$f $x\] \} - \} + 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 @@ -259,12 +259,12 @@ 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 + [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 @@ -279,15 +279,15 @@ 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\]\] \{ + proc square x { expr {$x * $x} } + generator foreach n [generator map square [nats]] { puts "n = $n" - if \{$n > 1000\} \{ break \} - \} + 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 @@ -294,12 +294,12 @@ 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\] + 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 @@ -312,37 +312,37 @@ 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\] - \# = \(\(\(\(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\]\] + # 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] + # = ((((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\] \} + 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 + sum [nats]; # Never returns - __generator__ __foldl__ *function* *zero* *generator* This is an alias for the __reduce__ command\. @@ -439,14 +439,14 @@ 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\}\] \} + 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\)\. @@ -481,12 +481,12 @@ 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 + 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 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 @@ -151,19 +151,19 @@ 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\] + % 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" - \} + % if {[dict exists $ptMetadata ele]} { + puts "at elevation [dict get $ptMetadata ele] meters" + } % ::gpx::Cleanup $token # REFERENCES 1. GPX: the GPS Exchange Format 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,11 +1,11 @@ [//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 -Redistribution permitted under the terms of the Open Publication License ) -[//000000004]: # (grammar::aycock\(n\) 1\.0 tcllib "Aycock\-Horspool\-Earley parser generator for Tcl") +[//000000003]: # (Copyright © 2006 by Kevin B\. Kenny ) +[//000000004]: # (Redistribution permitted under the terms of the Open Publication License ) +[//000000005]: # (grammar::aycock\(n\) 1\.0 tcllib "Aycock\-Horspool\-Earley parser generator for Tcl")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | KEYWORDS 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,11 +1,11 @@ [//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 -Copyright © 2007 Bogdan ) -[//000000004]: # (grammar::fa::dexec\(n\) 0\.2 tcllib "Finite automaton operations and usage") +[//000000003]: # (Copyright © 2004 Andreas Kupries ) +[//000000004]: # (Copyright © 2007 Bogdan ) +[//000000005]: # (grammar::fa::dexec\(n\) 0\.2 tcllib "Finite automaton operations and usage")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | *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 @@ -178,11 +178,11 @@ 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__\] + > *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, @@ -222,21 +222,21 @@ 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\. + 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\}\}\} + 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* @@ -462,11 +462,11 @@ - *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 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 @@ -481,11 +481,11 @@ - *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 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 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 @@ -116,17 +116,17 @@ 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 + (1) A <- a B c + (2a) B <- d B + (2b) B <- e - Some derivations, using starting expression A\. + Some derivations, using starting expression A. - A \-/1/\-> a B c \-/2a/\-> a d B c \-/2b/\-> a d e c + 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\. @@ -221,11 +221,11 @@ 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* __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 @@ -232,11 +232,11 @@ 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__\] + > *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 @@ -264,36 +264,36 @@ 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 + 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 \\\\ - \} + 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\. 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 @@ -80,15 +80,15 @@ 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\. +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: @@ -314,19 +314,19 @@ hook call ::model The __\.view__ megawidget displays the model state, and needs to know about model updates\. Consequently, it subscribes to the ::model's hook\. - hook bind ::model \.view \[list \.view ModelUpdate\] + hook bind ::model .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 + hook forget .view All bindings involving __\.view__ are deleted\. # Credits 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,9 +1,9 @@ [//000000001]: # (html \- HTML Generation) [//000000002]: # (Generated from file 'html\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (html\(n\) 1\.4\.4 tcllib "HTML Generation") +[//000000003]: # (html\(n\) 1\.5 tcllib "HTML Generation")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.2 -package require html ?1\.4\.4? +package require html ?1\.5? [__::html::author__ *author*](#1) [__::html::bodyTag__ *args*](#2) [__::html::cell__ *param value* ?*tag*?](#3) [__::html::checkbox__ *name value*](#4) @@ -67,38 +67,42 @@ [__::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::css__ *href*](#35) -[__::html::css\-clear__](#36) -[__::html::js__ *href*](#37) -[__::html::js\-clear__](#38) -[__::html::minorList__ *list* ?*ordered*?](#39) -[__::html::minorMenu__ *list* ?*sep*?](#40) -[__::html::nl2br__ *string*](#41) -[__::html::openTag__ *tag* ?*param*?](#42) -[__::html::paramRow__ *list* ?*rparam*? ?*cparam*?](#43) -[__::html::passwordInput__ ?*name*?](#44) -[__::html::passwordInputRow__ *label* ?*name*?](#45) -[__::html::quoteFormValue__ *value*](#46) -[__::html::radioSet__ *key sep list*](#47) -[__::html::radioValue__ *name value*](#48) -[__::html::refresh__ *seconds url*](#49) -[__::html::row__ *args*](#50) -[__::html::select__ *name param choices* ?*current*?](#51) -[__::html::selectPlain__ *name param choices* ?*current*?](#52) -[__::html::set__ *var val*](#53) -[__::html::submit__ *label* ?*name*?](#54) -[__::html::tableFromArray__ *arrname* ?*param*? ?*pat*?](#55) -[__::html::tableFromList__ *querylist* ?*param*?](#56) -[__::html::textarea__ *name* ?*param*? ?*current*?](#57) -[__::html::textInput__ *name value args*](#58) -[__::html::textInputRow__ *label name value args*](#59) -[__::html::varEmpty__ *name*](#60) -[__::html::while__ *test body*](#61) -[__::html::doctype__ *id*](#62) +[__::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) # DESCRIPTION The package __html__ provides commands that generate HTML\. These commands typically return an HTML string as their result\. In particular, they do not @@ -303,16 +307,36 @@ 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 *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__\. + *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* + - __::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__\. @@ -319,19 +343,19 @@ 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__\. @@ -338,119 +362,121 @@ 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*? + - __::html::passwordInput__ ?*name*? Generate an *input* tag of type *[password](\.\./\.\./\.\./\.\./index\.md\#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](\.\./\.\./\.\./\.\./index\.md\#password)*\. The *name* defaults to "password"\. - - __::html::quoteFormValue__ *value* + - __::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* + - __::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\. - - __::html::submit__ *label* ?*name*? + - __::html::submit__ *label* ?*name*? ?*title*? - Generate an *input* tag of type *submit*\. *name* defaults to "submit"\. + 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*? + - __::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* @@ -457,50 +483,50 @@ 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\. - - __::html::tableFromList__ *querylist* ?*param*? + - __::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\. - - __::html::textarea__ *name* ?*param*? ?*current*? + - __::html::textarea__ *name* ?*param*? ?*current*? Generate a *textarea* tag wrapped around its current values\. - - __::html::textInput__ *name value args* + - __::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\. - - __::html::textInputRow__ *label name value args* + - __::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\. - - __::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: @@ -525,10 +551,18 @@ 1. XHTML10F 1. XHTML11 1. XHTMLB + + - __::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\. # 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 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 @@ -104,13 +104,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... your own application code ... # COMMANDS - __::autoproxy::init__ @@ -238,20 +238,20 @@ # EXAMPLES package require autoproxy autoproxy::init - autoproxy::configure \-basic \-username ME \-password SEKRET - set tok \[http::geturl http://wiki\.tcl\.tk/\] + 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/\] + 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, 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,10 +1,10 @@ -[//000000001]: # (tool \- Tcl Web Server) +[//000000001]: # (httpd \- Tcl Web Server) [//000000002]: # (Generated from file 'httpd\.man' by tcllib/doctools with format 'markdown') [//000000003]: # (Copyright © 2018 Sean Woods ) -[//000000004]: # (tool\(n\) 4\.1\.1 tcllib "Tcl Web Server") +[//000000004]: # (httpd\(n\) 4\.3\.4 tcllib "Tcl Web Server")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
# NAME -tool \- A TclOO and coroutine based web server +httpd \- A TclOO and coroutine based web server # Table Of Contents - [Table Of Contents](#toc) @@ -23,45 +23,53 @@ - [Description](#section1) - [Minimal Example](#section2) - - [Class ::httpd::server](#section3) - - - [Class ::httpd::reply](#section4) - - - [Reply Method Ensembles](#section5) - - - [Reply Method Ensemble: http\_info](#section6) - - - [Reply Method Ensemble: request](#section7) - - - [Reply Method Ensemble: reply](#section8) - - - [Reply Methods](#section9) - - - [Class ::httpd::content](#section10) - - - [Class ::httpd::content\.cgi](#section11) - - - [Class ::httpd::content\.file](#section12) - - - [Class ::httpd::content\.proxy](#section13) - - - [Class ::httpd::content\.scgi](#section14) - - - [Class ::httpd::content\.websocket](#section15) - - - [SCGI Server Functions](#section16) - - - [Class ::httpd::reply\.scgi](#section17) - - - [Class ::httpd::server\.scgi](#section18) - - - [AUTHORS](#section19) - - - [Bugs, Ideas, Feedback](#section20) + - [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) @@ -68,72 +76,127 @@ - [Copyright](#copyright) # SYNOPSIS package require Tcl 8\.6 -package require httpd ?4\.1\.1? -package require sha1 -package require dicttool -package require oo::meta -package require oo::dialect -package require tool +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 -[constructor ?port ?port?? ?myaddr ?ipaddr?|all? ?server\_string ?string?? ?server\_name ?string??](#1) -[method __add\_uri__ *pattern* *dict*](#2) -[method __connect__ *sock* *ip* *port*](#3) -[method __Connect__ *uuid* *sock* *ip*](#4) -[method __[counter](\.\./counter/counter\.md)__ *which*](#5) -[method __CheckTimeout__](#6) -[method __dispatch__ *header\_dict*](#7) -[method __[log](\.\./log/log\.md)__ *args*](#8) -[method __port\_listening__](#9) -[method __PrefixNormalize__ *prefix*](#10) -[method __start__](#11) -[method __stop__](#12) -[method __template__ *page*](#13) -[method __TemplateSearch__ *page*](#14) -[method __Validate\_Connection__ *sock* *ip*](#15) -[method __ENSEMBLE::add__ *field* *element*](#16) -[method __ENSEMBLE::dump__](#17) -[method __ENSEMBLE::get__ *field*](#18) -[method __ENSEMBLE::reset__](#19) -[method __ENSEMBLE::remove__ *field* *element*](#20) -[method __ENSEMBLE::replace__ *keyvaluelist*](#21) -[method __ENSEMBLE::reset__](#22) -[method __ENSEMBLE::set__ *field* *value*](#23) -[method __http\_info::netstring__](#24) -[method __request::parse__ *string*](#25) -[method __reply::output__](#26) -[method __close__](#27) -[method __HttpHeaders__ *sock* *?debug?*](#28) -[method __dispatch__ *newsock* *datastate*](#29) -[method __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ *code* *?message?* *?errorInfo?*](#30) -[method __content__](#31) -[method __EncodeStatus__ *status*](#32) -[method FormData](#33) -[method MimeParse *mimetext*](#34) -[method __DoOutput__](#35) -[method PostData *length*](#36) -[method __puts__ *string*](#37) +[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 ____](#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) -[method __TransferComplete__ *args*](#41) -[method __Url\_Decode__ *string*](#42) -[method cgi\_info](#43) -[option __path__](#44) -[option __[prefix](\.\./\.\./\.\./\.\./index\.md\#prefix)__](#45) -[method proxy\_info](#46) -[method scgi\_info](#47) +[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) # 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 @@ -143,111 +206,80 @@ 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\. - tool::define ::reply\.hello \{ - method content \{\} \{ + oo::class create ::reply.hello { + method content {} { my puts "IRM Dispatch Server" - my puts "

Hello World\!

" + my puts "

Hello World!

" my puts - \} - \} - ::docserver::server create HTTPD port 8015 myaddr 127\.0\.0\.1 - HTTPD add\_uri /\* \[list mixin reply\.hello\] - -# Class ::httpd::server - -This class is the root object of the webserver\. It is responsible for opening -the socket and providing the initial connection negotiation\. - - - constructor ?port ?port?? ?myaddr ?ipaddr?|all? ?server\_string ?string?? ?server\_name ?string?? - - Build a new server object\. ?port? is the port to listen on - - - method __add\_uri__ *pattern* *dict* - - Set the hander for a URI pattern\. Information given in the *dict* is - stored in the data structure the __dispatch__ method uses\. If a field - called *mixin* is given, that class will be mixed into the reply object - immediately after construction\. - - - 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 __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\. Fields the server are looking for in particular are: class: A class - to use instead of the server's own *reply\_class* mixin: A class to be - mixed into the new object after construction\. All other fields are passed - along to the __http\_info__ structure of the reply object\. After the - class is created and the mixin is mixed in, the server invokes the reply - objects __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 __dispatch__ *header\_dict* - - Given a key/value list of information, return a data structure describing - how the server should reply\. - - - 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 __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 __start__ - - Open the socket listener\. - - - method __stop__ - - Shut off the socket listener, and destroy any pending replies\. - - - 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 __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::reply + } + } + ::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 @@ -270,205 +302,183 @@ the __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ method if an exception is raised\. 1. Invokes the __output__ method for the object -# Reply Method Ensembles - -The __http::reply__ class and its derivatives maintain several variables as -dictionaries internally\. Access to these dictionaries is managed through a -dedicated ensemble\. The ensemble implements most of the same behaviors as the -__[dict](\.\./\.\./\.\./\.\./index\.md\#dict)__ command\. Each ensemble implements -the following methods above, beyond, or modifying standard dicts: - - - method __ENSEMBLE::add__ *field* *element* - - Add *element* to a list stored in *field*, but only if it is not already - present om the list\. - - - method __ENSEMBLE::dump__ - - Return the current contents of the data structure as a key/value list\. - - - method __ENSEMBLE::get__ *field* - - Return the value of the field *field*, or an empty string if it does not - exist\. - - - method __ENSEMBLE::reset__ - - Return a key/value list of the default contents for this data structure\. - - - method __ENSEMBLE::remove__ *field* *element* - - Remove all instances of *element* from the list stored in *field*\. - - - method __ENSEMBLE::replace__ *keyvaluelist* - - Replace the internal dict with the contents of *keyvaluelist* - - - method __ENSEMBLE::reset__ - - Replace the internal dict with the default state\. - - - method __ENSEMBLE::set__ *field* *value* - - Set the value of *field* to *value*\. - -# Reply Method Ensemble: http\_info - -Manages HTTP headers passed in by the server\. Ensemble Methods: - - - method __http\_info::netstring__ - - Return the contents of this data structure as a netstring encoded block\. - -# Reply Method Ensemble: request - -Managed data from MIME headers of the request\. - - - method __request::parse__ *string* - - Replace the contents of the data structure with information encoded in a - MIME formatted block of text \(*string*\)\. - -# Reply Method Ensemble: reply - -Manage the headers sent in the reply\. - - - method __reply::output__ - - Return the contents of this data structure as a MIME encoded block - appropriate for an HTTP response\. - -# Reply Methods - - - method __close__ - - Terminate the transaction, and close the socket\. - - - method __HttpHeaders__ *sock* *?debug?* - - Stream MIME headers from the socket *sock*, stopping at an empty line\. - Returns the stream as a block of text\. - - - method __dispatch__ *newsock* *datastate* - - Take over control of the socket *newsock*, and store that as the *chan* - variable for the object\. This method runs through all of the steps of - reading HTTP headers, generating content, and closing the connection\. \(See - class writetup\)\. - - - method __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ *code* *?message?* *?errorInfo?* - - Generate an error message of the specified *code*, and display the - *message* as the reason for the exception\. *errorInfo* is passed in from - calls, but how or if it should be displayed is a prerogative of the - developer\. - - - method __content__ - - Generate the content for the reply\. This method is intended to be replaced - by the mixin\. 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: - - tool::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 \{\} \{ +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 http\_info get doc\_root\] - my variable reply\_file - set reply\_file \[file join $doc\_root index\.html\] - \} - \} - tool::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\] - \} - \} - tool::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\]\] - \} - \} - tool::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\}\] + 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 \{ + foreach {f v} $form { my puts "" - \} + } my puts "
$f$v

" my puts "Send some info:

" - my puts "

" + my puts "" my puts "" - foreach field \{name rank serial\_number\} \{ - set line "" my puts $line - \} + } my puts "
$field$field
" - my puts \[my html footer\] - \} - \} + my puts [my html footer] + } + } - - method __EncodeStatus__ *status* +__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 FormData + - 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 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 __DoOutput__ - - Generates the the HTTP reply, and streams that reply back across *chan*\. - - - method PostData *length* + - 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 __puts__ *string* + - 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\. @@ -483,117 +493,339 @@ Return the current system time in the format: %a, %d %b %Y %T %Z - - method __TransferComplete__ *args* - - Intended to be invoked from __chan copy__ as a callback\. This closes - every channel fed to it on the command line, and then destroys the object\. - - \#\#\# - \# 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 - if \{$length\} \{ - \#\#\# - \# Send any POST/PUT/etc content - \#\#\# - chan copy $sock $chan \-size $SIZE \-command \[info coroutine\] - yield - \} - catch \{close $sock\} - chan flush $chan - - - method __Url\_Decode__ *string* - - De\-httpizes a string\. - -# Class ::httpd::content - -The httpd module includes several ready to use implementations of content mixins -for common use cases\. Options are passed in to the __add\_uri__ method of the -server\. - -# Class ::httpd::content\.cgi - -An implementation to relay requests to process which will accept post data -streamed in vie stdin, and sent a reply streamed to stdout\. - - - method cgi\_info - - Mandatory method to be replaced by the end user\. If needed, activates the - process to proxy, and then returns a list of three values: *exec* \- The - arguments to send to exec to fire off the responding process, minus the - stdin/stdout redirection\. - -# Class ::httpd::content\.file - -An implementation to deliver files from the local file system\. - - - option __path__ - - The root directory on the local file system to be exposed via http\. - - - option __[prefix](\.\./\.\./\.\./\.\./index\.md\#prefix)__ - - The prefix of the URI portion to ignore when calculating relative file - paths\. - -# Class ::httpd::content\.proxy - -An implementation to relay requests to another HTTP server, and relay the -results back across the request channel\. - - - method proxy\_info - - Mandatory method to be replaced by the end user\. If needed, activates the - process to proxy, and then returns a list of three values: *proxyhost* \- - The hostname where the proxy is located *proxyport* \- The port to connect - to *proxyscript* \- A pre\-amble block of text to send prior to the mirrored - request - -# Class ::httpd::content\.scgi - -An implementation to relay requests to a server listening on a socket expecting -SCGI encoded requests, and relay the results back across the request channel\. - - - method scgi\_info - - Mandatory method to be replaced by the end user\. If needed, activates the - process to proxy, and then returns a list of three values: *scgihost* \- - The hostname where the scgi listener is located *scgiport* \- The port to - connect to *scgiscript* \- The contents of the *SCRIPT\_NAME* header to be - sent - -# Class ::httpd::content\.websocket - -A placeholder for a future implementation to manage requests that can expect to -be promoted to a Websocket\. Currently it is an empty class\. - -# SCGI Server Functions - -The HTTP module also provides an SCGI server implementation, as well as an HTTP -implementation\. To use the SCGI functions, create an object of the -__http::server\.scgi__ class instead of the __http::server__ class\. - -# Class ::httpd::reply\.scgi - -An modified __http::reply__ implementation that understands how to deal with -netstring encoded headers\. - -# Class ::httpd::server\.scgi - -A modified __http::server__ which is tailored to replying to request -according to the SCGI standard instead of the HTTP standard\. - -# AUTHORS +## 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 +# 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\. 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 @@ -33,15 +33,17 @@ - [Bugs, Ideas, Feedback](#section6) - [See Also](#seealso) - [Keywords](#keywords) + + - [Category](#category) # SYNOPSIS package require Tcl 8\.5 -package require imap4 ?0\.5\.2? +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) @@ -94,13 +96,13 @@ 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 + 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 @@ -131,11 +133,11 @@ 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\}\} + {{Arc08 noselect} {Arc08/Private {noinferiors unmarked}} {INBOX noinferiors}} - __::imap4::select__ *chan* ?*mailbox*? Select a mailbox, 0 is returned on success\. @@ -204,11 +206,11 @@ \- 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\}\}\} + {{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 @@ -246,11 +248,11 @@ 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" + 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 @@ -327,11 +329,11 @@ 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\]" + 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 @@ -388,11 +390,11 @@ Remove the flags in *flaglist* to the existing flags for the message\. For example: - ::imap4::store $chan $start\_msgid:$end\_msgid \+FLAGS "Deleted" + ::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\. @@ -421,37 +423,37 @@ # EXAMPLES set user myusername set pass xtremescrt - set server imap\.test\.tld + set server imap.test.tld set FOLDER INBOX - \# Connect to server - set imap \[::imap4::open $server\] + # 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 + # 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 @@ -471,13 +473,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... your own application code ... # REFERENCES Mark R\. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL \- VERSION 4rev1", RFC 3501, March 2003, @@ -511,5 +513,9 @@ [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 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 @@ -89,12 +89,12 @@ # CALLBACK The callback must look like: - proc Callback \{context state args\} \{ - \} + 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__ 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,13 +1,13 @@ [//000000001]: # (jpeg \- JPEG image manipulation) [//000000002]: # (Generated from file 'jpeg\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004\-2005, Code: Aaron Faupell -Copyright © 2007, Code: Andreas Kupries -Copyright © 2004\-2009, Doc: Andreas Kupries -Copyright © 2011, Code: Pat Thoyts ) -[//000000004]: # (jpeg\(n\) 0\.5 tcllib "JPEG image manipulation") +[//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 | __::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 \{ + set exif { Make Canon - Model \{Canon DIGITAL IXUS\} - DateTime \{2001:06:09 15:17:32\} - \} + 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*? @@ -131,16 +131,16 @@ 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\]\] \{ + 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\)\]\] + 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 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,11 +1,11 @@ [//000000001]: # (json \- JSON) [//000000002]: # (Generated from file 'json\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 ActiveState Software Inc\. -Copyright © 2009 Thomas Maeder, Glue Software Engineering AG) -[//000000004]: # (json\(n\) 1\.3\.4 tcllib "JSON") +[//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 | 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, + "Latitude": 37.7668, + "Longitude": -122.3959, "Address": "", "City": "SAN FRANCISCO", "State": "CA", "Zip": "94107", "Country": "US" - \}, - \{ + }, + { "precision": "zip", - "Latitude": 37\.371991, - "Longitude": \-122\.026020, + "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\} + {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": \{ + { + "Image": { "Width": 800, "Height": 600, "Title": "View from 15th Floor", - "Thumbnail": \{ - "Url": "http://www\.example\.com/image/481989943", + "Thumbnail": { + "Url": "http://www.example.com/image/481989943", "Height": 125, "Width": "100" - \}, - "IDs": \[116, 943, 234, 38793\] - \} - \} + }, + "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\}\} + 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)__\. 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 @@ -50,32 +50,32 @@ 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\} \{ - \.\.\.\. - \}\}\} + set f {::apply {{x} { + .... + }}} with its deep nesting of braces, or - set f \[list ::apply \{\{x y\} \{ - \.\.\.\. - \}\} $value\_for\_x\] + 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\} \{ - \.\.\.\. - \}\] + set f [lambda {x} { + .... + }] and - set f \[lambda \{x y\} \{ - \.\.\.\. - \} $value\_for\_x\] + set f [lambda {x y} { + .... + } $value_for_x] # COMMANDS - __::lambda__ *arguments* *body* ?*arg*\.\.\.? 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 @@ -66,31 +66,31 @@ 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\} \{ + ::lazyset::variable page {apply {{name} { package require http - set token \[http::geturl http://www\.tcl\.tk/\] - set data \[http::data $token\] + 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\} \{ + ::lazyset::variable -array true page {apply {{name index} { package require http - set token \[http::geturl $index\] - set data \[http::data $token\] + set token [http::geturl $index] + set data [http::data $token] return $data - \}\}\} + }}} - puts $page\(http://www\.tcl\.tk/\) + puts $page(http://www.tcl.tk/) - ::lazyset::variable \-appendArgs false simple \{ - return \-level 0 42 - \} + ::lazyset::variable -appendArgs false simple { + return -level 0 42 + } puts $simple # AUTHORS 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,12 +1,12 @@ [//000000001]: # (ldap \- LDAP client) [//000000002]: # (Generated from file 'ldap\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Andreas Kupries -Copyright © 2004 Jochen Loewer -Copyright © 2006 Michael Schlenker ) -[//000000004]: # (ldap\(n\) 1\.9\.2 tcllib "LDAP client") +[//000000003]: # (Copyright © 2004 Andreas Kupries ) +[//000000004]: # (Copyright © 2004 Jochen Loewer ) +[//000000005]: # (Copyright © 2006 Michael Schlenker ) +[//000000006]: # (ldap\(n\) 1\.9\.2 tcllib "LDAP client")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | COMMANDS - __::ldap::connect__ *host* ?*port*? @@ -135,11 +135,11 @@ hostname is used as the hostname for Server Name Indication in the TLS handshake\. Use __::tls::init__ to setup defaults for trusted certificates\. - tls::init \-cadir /etc/ssl/certs/ca\-certificates\.crt + tls::init -cadir /etc/ssl/certs/ca-certificates.crt 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\. @@ -193,17 +193,17 @@ 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\*\)" + 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 \.\.\.\} \.\.\.\}\} \.\.\. + {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 @@ -220,11 +220,11 @@ __::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 \.\.\. \} + {-option1 value1 -option2 value2 ... } Following options are available: * __\-scope__ base one sub @@ -271,11 +271,11 @@ 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\.\.\.\} \.\.\.\} + dn {attr1 {val11 val12 ...} attr2 {val21...} ...} The __::ldap::searchNext__ command returns an empty list at the end of the search\. - __::ldap::searchEnd__ *handle* @@ -322,11 +322,11 @@ 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\.\.\.\} \.\.\. + 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\) @@ -433,95 +433,95 @@ 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 + # Connect, bind, add a new object, modify it in various ways - set handle \[ldap::connect localhost 9009\] + 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 \{ + ldap::add $handle $dn { objectClass OpenLDAPperson - cn \{Test User\} - mail test\.user@google\.com + cn {Test User} + mail test.user@google.com uid testuid sn User - telephoneNumber \+31415926535 - telephoneNumber \+27182818285 - \} + 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::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\. + # 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\] + 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 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\] - \} + 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\] - \} - \} + 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 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 @@ -353,64 +353,64 @@ ## Entry Example package require ldapx - \# - \# Create an entry and fill it as a standard entry with - \# attributes and values - \# + # + # 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 set "objectClass" {person anotherObjectClass} e set1 "givenName" "Joe" e set1 "sn" "User" - e set "telephoneNumber" \{\+31415926535 \+2182818\} + 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%\] + 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\]" + 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\. - \# + # + # 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\]" + puts stdout "$c\n[$c print]" - \# - \# Apply changes to first entry\. It should be the same as the - \# second entry, now\. - \# + # + # 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\]" + puts stdout "nc\n[nc print]" - \# - \# Clean\-up - \# + # + # Clean-up + # e destroy $b destroy c destroy nc destroy @@ -554,54 +554,54 @@ ## Ldap Example package require ldapx - \# - \# Connects to the LDAP directory - \# + # + # 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\]" + 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 - \# + # + # Search all entries matching some criterion + # - l configure \-scope one + 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\]" + 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\. - \# + # + # 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\*\)" \{\}\] + set lent [l search "ou=people,o=mycomp" "(sn=Joe*)" {}] ::ldapx::entry create c - foreach e $lent \{ + foreach e $lent { $e backup - $e add1 "telephoneNumber" "\+31415926535" + $e add1 "telephoneNumber" "+31415926535" c diff $e - if \{\! \[l commit c\]\} then \{ - puts stderr "error: \[l error\]" + if {! [l commit c]} then { + puts stderr "error: [l error]" exit 1 - \} + } $e destroy - \} + } c destroy l disconnect l destroy @@ -689,46 +689,46 @@ ## 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\. + # 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\]" + if {! [la connect "ldap://server.mycomp.com"]} then { + puts stderr "error: [la error]" exit 1 - \} - la configure \-scope one + } + la configure -scope one - \# Reads LDIF file + # 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 \{ + 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 \{ + if {[llength [c change]] != 0} then { liout write c - \} - \} + } + } la disconnect la destroy e1 destroy e2 destroy 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 @@ -80,11 +80,11 @@ 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 + 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__ @@ -102,11 +102,11 @@ 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\\"" + 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 @@ -241,11 +241,11 @@ 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::logsubst debug {XML of node $node is '[$node toXml]'} - __::log::logMsg__ *text* Convenience wrapper around __::log::log__\. Equivalent to __::log::log info text__\. 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 @@ -83,17 +83,17 @@ 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" + set log [logger::init myservice] + ${log}::notice "Initialized myservice logging" - \.\.\. code \.\.\. + ... code ... - $\{log\}::notice "Ending myservice logging" - $\{log\}::delete + ${log}::notice "Ending myservice logging" + ${log}::delete In the above code, after the package is loaded, the following things happen: - __logger::init__ *service* @@ -210,14 +210,14 @@ 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\} \{ + proc lvlcallback {old new} { puts "Loglevel changed from $old to $new" - \} - $\{log\}::lvlchangeproc lvlcallback + } + ${log}::lvlchangeproc lvlcallback - __$\{log\}::logproc__ *level* - __$\{log\}::logproc__ *level* *command* @@ -233,16 +233,16 @@ 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\} \{ + proc logtoserver {txt} { variable socket puts $socket "Notice: $txt" - \} + } - $\{log\}::logproc notice logtoserver + ${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: @@ -289,11 +289,11 @@ 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}::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\. @@ -304,40 +304,40 @@ 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 \} \{ + proc tracecmd { dict } { puts $dict - \} + } - set log \[::logger::init example\] - $\{log\}::logproc trace tracecmd + set log [::logger::init example] + ${log}::logproc trace tracecmd - proc foo \{ args \} \{ + proc foo { args } { puts "In foo" bar 1 - return "foo\_result" - \} + return "foo_result" + } - proc bar \{ x \} \{ + proc bar { x } { puts "In bar" - return "bar\_result" - \} + return "bar_result" + } - $\{log\}::trace add foo bar - $\{log\}::trace on + ${log}::trace add foo bar + ${log}::trace on foo - \# Output: - enter \{proc ::foo level 1 script \{\} caller \{\} procargs \{args \{\}\}\} + # Output: + enter {proc ::foo level 1 script {} caller {} procargs {args {}}} In foo - enter \{proc ::bar level 2 script \{\} caller ::foo procargs \{x 1\}\} + 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\} + 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 @@ -409,31 +409,31 @@ 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\} \{ + # 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\]\] - \} - \} + } else { + lappend val $var [uplevel 1 [list set $var]] + } + } puts "$txt" puts "Caller: $caller" puts "Variables in callers scope:" - foreach \{var value\} $val \{ + foreach {var value} $val { puts "$var = $value" - \} - \} + } + } - \# install as logproc - $\{log\}::logproc debug log\_local\_var + # 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 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,10 +1,10 @@ [//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 tcllib "Object Oriented logging facility") +[//000000004]: # (logger::utils\(n\) 1\.3\.1 tcllib "Object Oriented logging facility")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.4 -package require logger::utils ?1\.3? +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) @@ -132,11 +132,11 @@ 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\}\} + logger::utils::applyAppender -serviceCmd $log -appender console -appenderArgs {-conversionPattern {\[%M\] \[%p\] - %m}} The usual Tcl quoting rules apply\. * __\-levels__ levelList @@ -143,15 +143,15 @@ The list of levels to apply this appender to\. If not specified all levels are assumed\. Example of usage: - % set log \[logger::init testLog\] + % 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::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 @@ -158,13 +158,13 @@ __::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" + 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 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 @@ -65,11 +65,11 @@ - __::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\] \} + 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*\. 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,9 +1,9 @@ [//000000001]: # (markdown \- Markdown to HTML Converter) [//000000002]: # (Generated from file 'markdown\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (markdown\(n\) 1\.1 tcllib "Markdown to HTML Converter") +[//000000003]: # (markdown\(n\) 1\.1\.1 tcllib "Markdown to HTML Converter")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.5 -package require Markdown 1\.1 +package require Markdown 1\.1\.1 package require textutil ?0\.8? [__::Markdown::convert__ *markdown*](#1) [__::Markdown::register__ *langspec* *converter*](#2) [__::Markdown::get\_lang\_counter__](#3) 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 @@ -132,20 +132,20 @@ *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 + # 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 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 @@ -153,13 +153,13 @@ 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\] + 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 @@ -166,13 +166,13 @@ 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 + 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*? @@ -180,14 +180,14 @@ 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 + 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\. @@ -204,14 +204,14 @@ 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" + 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* @@ -254,23 +254,23 @@ * 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 + 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\. @@ -363,72 +363,72 @@ 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\) + 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 + 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\]\] + 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\.\.\. + 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 + 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\. + 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 @@ -438,70 +438,70 @@ 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\]\]\] + # + # 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::\* + 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\] + # 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\} \{ + # 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 + 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\]\]" + 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* 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,11 +1,11 @@ [//000000001]: # (math::bignum \- Tcl Math Library) [//000000002]: # (Generated from file 'bignum\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Salvatore Sanfilippo -Copyright © 2004 Arjen Markus ) -[//000000004]: # (math::bignum\(n\) 3\.1 tcllib "Tcl Math Library") +[//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 | 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 + # 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\]\] - \} + 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\]\] + puts [::math::bignum::tostr [fact 100]] # API - __::math::bignum::fromstr__ *string* ?*radix*? 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 @@ -249,26 +249,26 @@ 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\) + -- 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\) + 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\) + 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* @@ -320,11 +320,11 @@ - __::math::calculus::newtonRaphson__ *func* *deriv* *initval* Determine the root of an equation given by - func\(x\) = 0 + func(x) = 0 using the method of Newton\-Raphson\. The procedure takes the following arguments: * *func* @@ -389,31 +389,31 @@ 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 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 \{ + 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\] - \} - \} + 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\) @@ -424,66 +424,66 @@ 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\]" + 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\}\]" + 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 + x'' + rx' + wx = 0 can be split into a system of first\-order equations: x' = y - y' = \-ry \- wx + 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\}\] + 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 + 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\] + 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 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 @@ -50,18 +50,18 @@ 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 + 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\) \) + exp( ln_Gamma( x) ) is computed is expected to be precise to better than nine significant figures\. - __::math::factorial__ *x* @@ -84,11 +84,11 @@ - __::math::choose__ *n k* Returns the binomial coefficient *C\(n, k\)* - C\(n,k\) = n\! / k\! \(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 @@ -96,11 +96,11 @@ - __::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\) + 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 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 @@ -57,11 +57,11 @@ 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\)\)\}\] + variable radtodeg [expr {180.0/(4.0*atan(1.0))}] and use the variable radtodeg whenever you need the conversion\. This has two drawbacks: @@ -87,11 +87,11 @@ - 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\}\] + 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)\. 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 @@ -108,31 +108,31 @@ 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\. + # 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* 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,11 +1,11 @@ [//000000001]: # (math::exact \- Tcl Math Library) [//000000002]: # (Generated from file 'exact\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2015 Kevin B\. Kenny -Redistribution permitted under the terms of the Open Publication License ) -[//000000004]: # (math::exact\(n\) 1\.0\.1 tcllib "Tcl Math Library") +[//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 | = 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\] + 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": 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,11 +1,11 @@ [//000000001]: # (math::interpolate \- Tcl Math Library) [//000000002]: # (Generated from file 'interpolate\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Arjen Markus -Copyright © 2004 Kevn B\. Kenny ) -[//000000004]: # (math::interpolate\(n\) 1\.1 tcllib "Tcl Math Library") +[//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 | Bugs, Ideas, Feedback 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,12 +1,12 @@ [//000000001]: # (math::linearalgebra \- Tcl Math Library) [//000000002]: # (Generated from file 'linalg\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004\-2008 Arjen Markus -Copyright © 2004 Ed Hume -Copyright © 2008 Michael Buadin ) -[//000000004]: # (math::linearalgebra\(n\) 1\.1\.5 tcllib "Tcl Math Library") +[//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 | REMARKS ON THE IMPLEMENTATION @@ -1128,21 +1128,21 @@ 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 \.\.\. - \} + 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 \{ + namespace eval compute { rename ::scale scaleTk - scaleTk \.scale \.\.\. - \} + 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 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 @@ -54,15 +54,15 @@ 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 + x = +/- d1 d2 ... dt basis^e where digits satisfy - 0 <= di <= basis \- 1, i = 1, t + 0 <= di <= basis - 1, i = 1, t with the convention : - t is the size of the mantissa @@ -75,61 +75,61 @@ # 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 + % 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%\] + set pp [machineparameters create %AUTO%] $pp compute $pp print $pp destroy This prints out : Machine parameters - Epsilon : 1\.11022302463e\-16 + 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 + 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 + 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%\] + set pp [machineparameters create %AUTO%] $pp compute - set eps \[$pp get \-epsilon\] + set eps [$pp get -epsilon] $pp destroy # REFERENCES - "Algorithms to Reveal Properties of Floating\-Point Arithmetic", Michael A\. 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,13 +1,13 @@ [//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 -Copyright © 2010 by Andreas Kupries -Copyright © 2010 by Kevin Kenny -Copyright © 2018 by Arjen Markus) -[//000000004]: # (math::geometry\(n\) 1\.3\.0 tcllib "Tcl Math Library") +[//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]: # (math::geometry\(n\) 1\.3\.0 tcllib "Tcl Math Library")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | DESCRIPTION The __math::geometry__ package is a collection of functions for computations and manipulations on two\-dimensional geometrical objects, such as points, lines @@ -153,11 +156,11 @@ - __::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 [math::geomtry::- point1 point2] - __::math::geometry::length__ *point* Compute the length of the vector and return it as the result of the command\. @@ -231,11 +234,47 @@ * list *line* Coordinates of the line - - __::math::geometry::calculateDistanceToLine__ *P* *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* @@ -244,11 +283,11 @@ * list *line* List of four numbers, the coordinates of two points on the line - - __::math::geometry::calculateDistanceToLineSegment__ *P* *linesegment* + - __::math::geometry::calculateDistanceToLineSegment__ *P* *linesegment* Calculate the distance of point P to the \(finite\) line segment and return the result\. * list *P* @@ -258,11 +297,11 @@ * list *linesegment* List of four numbers, the coordinates of the first and last points of the line segment - - __::math::geometry::calculateDistanceToPolyline__ *P* *polyline* + - __::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* @@ -271,11 +310,11 @@ * list *polyline* List of numbers, the coordinates of the vertices of the polyline - - __::math::geometry::calculateDistanceToPolygon__ *P* *polygon* + - __::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\. @@ -285,11 +324,11 @@ * list *polygon* List of numbers, the coordinates of the vertices of the polygon - - __::math::geometry::findClosestPointOnLine__ *P* *line* + - __::math::geometry::findClosestPointOnLine__ *P* *line* Return the point on a line which is closest to a given point\. * list *P* @@ -297,11 +336,11 @@ * list *line* List of four numbers, the coordinates of two points on the line - - __::math::geometry::findClosestPointOnLineSegment__ *P* *linesegment* + - __::math::geometry::findClosestPointOnLineSegment__ *P* *linesegment* Return the point on a *line segment* which is closest to a given point\. * list *P* @@ -309,11 +348,11 @@ * list *linesegment* List of four numbers, the first and last points on the line segment - - __::math::geometry::findClosestPointOnPolyline__ *P* *polyline* + - __::math::geometry::findClosestPointOnPolyline__ *P* *polyline* Return the point on a *polyline* which is closest to a given point\. * list *P* @@ -321,19 +360,19 @@ * list *polyline* List of numbers, the vertices of the polyline - - __::math::geometry::lengthOfPolyline__ *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* + - __::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* @@ -346,11 +385,11 @@ * list *dist* Distance over which to move the point - - __::math::geometry::lineSegmentsIntersect__ *linesegment1* *linesegment2* + - __::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 @@ -361,11 +400,11 @@ * list *linesegment2* Second line segment - - __::math::geometry::findLineSegmentIntersection__ *linesegment1* *linesegment2* + - __::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\)\. @@ -375,11 +414,11 @@ * list *linesegment2* Second line segment - - __::math::geometry::findLineIntersection__ *line1* *line2* + - __::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\)\. @@ -392,11 +431,11 @@ Second line See section [References](#section3) for details on the algorithm and math behind it\. - - __::math::geometry::polylinesIntersect__ *polyline1* *polyline2* + - __::math::geometry::polylinesIntersect__ *polyline1* *polyline2* Check if two polylines intersect or not \(in two dimensions only\)\. * list *polyline1* @@ -404,11 +443,11 @@ * list *polyline2* Second polyline - - __::math::geometry::polylinesBoundingIntersect__ *polyline1* *polyline2* *granularity* + - __::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\. @@ -428,11 +467,11 @@ * int *granularity* Number of points in each part \(<=1 means check every edge\) - - __::math::geometry::intervalsOverlap__ *y1* *y2* *y3* *y4* *strict* + - __::math::geometry::intervalsOverlap__ *y1* *y2* *y3* *y4* *strict* Check if two intervals overlap\. * double *y1,y2* @@ -444,11 +483,11 @@ * logical *strict* Check for strict or non\-strict overlap - - __::math::geometry::rectanglesOverlap__ *P1* *P2* *Q1* *Q2* *strict* + - __::math::geometry::rectanglesOverlap__ *P1* *P2* *Q1* *Q2* *strict* Check if two rectangles overlap\. * list *P1* @@ -468,20 +507,20 @@ * list *strict* choosing strict or non\-strict interpretation - - __::math::geometry::bbox__ *polyline* + - __::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* + - __::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* @@ -490,11 +529,11 @@ * list *polyline* The polyline to be examined - - __::math::geometry::pointInsidePolygonAlt__ *P* *polyline* + - __::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\. @@ -505,11 +544,11 @@ * list *polyline* The polyline to be examined - - __::math::geometry::rectangleInsidePolygon__ *P1* *P2* *polyline* + - __::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* @@ -522,43 +561,43 @@ * list *polygon* The polygon in question - - __::math::geometry::areaPolygon__ *polygon* + - __::math::geometry::areaPolygon__ *polygon* Calculate the area of a polygon\. * list *polygon* The polygon in question - - __::math::geometry::translate__ *vector* *polyline* + - __::math::geometry::translate__ *vector* *polyline* Translate a polyline over a given vector * list *vector* Translation vector * list *polyline* - The polyline to be rotated + The polyline to be translated - - __::math::geometry::rotate__ *angle* *polyline* + - __::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 + The polyline to be rotated - - __::math::geometry::reflect__ *angle* *polyline* + - __::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* @@ -567,27 +606,27 @@ * list *polyline* The polyline to be reflected - - __::math::geometry::degToRad__ *angle* + - __::math::geometry::degToRad__ *angle* Convert from degrees to radians * list *angle* Angle in degrees - - __::math::geometry::radToDeg__ *angle* + - __::math::geometry::radToDeg__ *angle* Convert from radians to degrees * list *angle* Angle in radians - - __::math::geometry::circle__ *centre* *radius* + - __::math::geometry::circle__ *centre* *radius* Convenience procedure to create a circle from a point and a radius\. * list *centre* @@ -595,11 +634,11 @@ * list *radius* Radius of the circle - - __::math::geometry::circleTwoPoints__ *point1* *point2* + - __::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\. @@ -609,11 +648,11 @@ * list *point2* Second point - - __::math::geometry::pointInsideCircle__ *point* *circle* + - __::math::geometry::pointInsideCircle__ *point* *circle* Determine if the given point is inside the circle or on the circumference \(1\) or outside \(0\)\. * list *point* @@ -622,11 +661,11 @@ * list *circle* Circle that may or may not contain the point - - __::math::geometry::lineIntersectsCircle__ *line* *circle* + - __::math::geometry::lineIntersectsCircle__ *line* *circle* Determine if the given line intersects the circle or touches it \(1\) or does not \(0\)\. * list *line* @@ -635,11 +674,11 @@ * list *circle* Circle that may or may not be intersected - - __::math::geometry::lineSegmentIntersectsCircle__ *segment* *circle* + - __::math::geometry::lineSegmentIntersectsCircle__ *segment* *circle* Determine if the given line segment intersects the circle or touches it \(1\) or does not \(0\)\. * list *segment* @@ -648,11 +687,11 @@ * list *circle* Circle that may or may not be intersected - - __::math::geometry::intersectionLineWithCircle__ *line* *circle* + - __::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\.\) @@ -663,11 +702,11 @@ * list *circle* Circle that may or may not be intersected - - __::math::geometry::intersectionCircleWithCircle__ *circle1* *circle2* + - __::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\.\) @@ -678,11 +717,11 @@ * list *circle2* Second circle - - __::math::geometry::tangentLinesToCircle__ *point* *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\.\) 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 @@ -51,10 +51,11 @@ [__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\. @@ -215,27 +216,40 @@ Estimate the number of primes according the formula by Gauss\. * integer *N* \(in\) - Number in question + 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 + 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 + 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 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,11 +1,11 @@ [//000000001]: # (math::optimize \- Tcl Math Library) [//000000002]: # (Generated from file 'optimize\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Arjen Markus -Copyright © 2004,2005 Kevn B\. Kenny ) -[//000000004]: # (math::optimize\(n\) 1\.0 tcllib "Tcl Math Library") +[//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 | = 0 and y >= 0 \(implicit constraints, part of the - definition of linear programs\) + 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 + 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 \} \} \] + 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 + x + y >= 1 can be turned into standard form using: - \-x \-y <= \-1 + -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\. 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 @@ -70,15 +70,15 @@ - __::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 + 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\] + set f [::math::polynomials::polynomial [list $a $b $c $d] * list *coeffs* Coefficients of the polynomial \(in ascending order\) 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 @@ -71,18 +71,18 @@ 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\] + set z [complex 0 1] + puts "z = [tostring $z]" + puts "z**2 = [* $z $z] would result in: z = i - z\*\*2 = \-1 + z**2 = -1 # AVAILABLE PROCEDURES The package implements all or most basic operations and elementary functions\. ADDED embedded/md/tcllib/files/modules/math/quasirandom.md Index: embedded/md/tcllib/files/modules/math/quasirandom.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/math/quasirandom.md @@ -0,0 +1,167 @@ + +[//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 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 @@ -68,17 +68,17 @@ - __::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 + 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\]\] + 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\) 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 @@ -284,40 +284,40 @@ 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\) \}\] - \} + 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\) \}\]\]\] - \} + 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 \) \} - \} + 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\] + 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 + 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 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,10 +1,10 @@ [//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\.3 tcllib "Tcl Math Library") +[//000000004]: # (math::special\(n\) 0\.4 tcllib "Tcl Math Library")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS -package require Tcl ?8\.3? -package require math::special ?0\.3? +package require Tcl ?8\.5? +package require math::special ?0\.4? [__::math::special::Beta__ *x* *y*](#1) -[__::math::special::Gamma__ *x*](#2) -[__::math::special::erf__ *x*](#3) -[__::math::special::erfc__ *x*](#4) -[__::math::special::invnorm__ *p*](#5) -[__::math::special::J0__ *x*](#6) -[__::math::special::J1__ *x*](#7) -[__::math::special::Jn__ *n* *x*](#8) -[__::math::special::J1/2__ *x*](#9) -[__::math::special::J\-1/2__ *x*](#10) -[__::math::special::I\_n__ *x*](#11) -[__::math::special::cn__ *u* *k*](#12) -[__::math::special::dn__ *u* *k*](#13) -[__::math::special::sn__ *u* *k*](#14) -[__::math::special::elliptic\_K__ *k*](#15) -[__::math::special::elliptic\_E__ *k*](#16) -[__::math::special::exponential\_Ei__ *x*](#17) -[__::math::special::exponential\_En__ *n* *x*](#18) -[__::math::special::exponential\_li__ *x*](#19) -[__::math::special::exponential\_Ci__ *x*](#20) -[__::math::special::exponential\_Si__ *x*](#21) -[__::math::special::exponential\_Chi__ *x*](#22) -[__::math::special::exponential\_Shi__ *x*](#23) -[__::math::special::fresnel\_C__ *x*](#24) -[__::math::special::fresnel\_S__ *x*](#25) -[__::math::special::sinc__ *x*](#26) -[__::math::special::legendre__ *n*](#27) -[__::math::special::chebyshev__ *n*](#28) -[__::math::special::laguerre__ *alpha* *n*](#29) -[__::math::special::hermite__ *n*](#30) +[__::math::special::incBeta__ *a* *b* *x*](#2) +[__::math::special::regIncBeta__ *a* *b* *x*](#3) +[__::math::special::Gamma__ *x*](#4) +[__::math::special::digamma__ *x*](#5) +[__::math::special::erf__ *x*](#6) +[__::math::special::erfc__ *x*](#7) +[__::math::special::invnorm__ *p*](#8) +[__::math::special::J0__ *x*](#9) +[__::math::special::J1__ *x*](#10) +[__::math::special::Jn__ *n* *x*](#11) +[__::math::special::J1/2__ *x*](#12) +[__::math::special::J\-1/2__ *x*](#13) +[__::math::special::I\_n__ *x*](#14) +[__::math::special::cn__ *u* *k*](#15) +[__::math::special::dn__ *u* *k*](#16) +[__::math::special::sn__ *u* *k*](#17) +[__::math::special::elliptic\_K__ *k*](#18) +[__::math::special::elliptic\_E__ *k*](#19) +[__::math::special::exponential\_Ei__ *x*](#20) +[__::math::special::exponential\_En__ *n* *x*](#21) +[__::math::special::exponential\_li__ *x*](#22) +[__::math::special::exponential\_Ci__ *x*](#23) +[__::math::special::exponential\_Si__ *x*](#24) +[__::math::special::exponential\_Chi__ *x*](#25) +[__::math::special::exponential\_Shi__ *x*](#26) +[__::math::special::fresnel\_C__ *x*](#27) +[__::math::special::fresnel\_S__ *x*](#28) +[__::math::special::sinc__ *x*](#29) +[__::math::special::legendre__ *n*](#30) +[__::math::special::chebyshev__ *n*](#31) +[__::math::special::laguerre__ *alpha* *n*](#32) +[__::math::special::hermite__ *n*](#33) # DESCRIPTION This package implements several so\-called special functions, like the Gamma function, the Bessel functions and such\. @@ -111,51 +114,56 @@ 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 + 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\. @@ -165,13 +173,11 @@ - 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 + - The incomplete gamma function # PROCEDURES The package defines the following public procedures: @@ -185,62 +191,104 @@ * float *y* Second argument for the Beta function - - __::math::special::Gamma__ *x* + - __::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::erf__ *x* + - __::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* + - __::math::special::erfc__ *x* Compute the complementary error function for argument "x" * float *x* Argument for the complementary error function - - __::math::special::invnorm__ *p* + - __::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* + - __::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* + - __::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* + - __::math::special::Jn__ *n* *x* Compute the nth\-order Bessel function of the first kind for the argument "x" * integer *n* @@ -248,29 +296,29 @@ * float *x* Argument for the Bessel function - - __::math::special::J1/2__ *x* + - __::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* + - __::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* + - __::math::special::I\_n__ *x* Compute the modified Bessel function of the first kind of order n for the argument "x" * int *x* @@ -279,11 +327,11 @@ * float *x* Argument for the function - - __::math::special::cn__ *u* *k* + - __::math::special::cn__ *u* *k* Compute the elliptic function *cn* for the argument "u" and parameter "k"\. * float *u* @@ -291,11 +339,11 @@ * float *k* Parameter - - __::math::special::dn__ *u* *k* + - __::math::special::dn__ *u* *k* Compute the elliptic function *dn* for the argument "u" and parameter "k"\. * float *u* @@ -303,11 +351,11 @@ * float *k* Parameter - - __::math::special::sn__ *u* *k* + - __::math::special::sn__ *u* *k* Compute the elliptic function *sn* for the argument "u" and parameter "k"\. * float *u* @@ -315,37 +363,37 @@ * float *k* Parameter - - __::math::special::elliptic\_K__ *k* + - __::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* + - __::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* + - __::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* + - __::math::special::exponential\_En__ *n* *x* Compute the exponential integral of the first kind for the argument "x" and order n * int *n* @@ -354,92 +402,92 @@ * float *x* Argument for the function \(x >= 0\) - - __::math::special::exponential\_li__ *x* + - __::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* + - __::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* + - __::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* + - __::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* + - __::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* + - __::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* + - __::math::special::fresnel\_S__ *x* Compute the Fresnel sine integral for real argument x * float *x* Argument for the function - - __::math::special::sinc__ *x* + - __::math::special::sinc__ *x* Compute the sinc function for real argument x * float *x* Argument for the function - - __::math::special::legendre__ *n* + - __::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* + - __::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* + - __::math::special::laguerre__ *alpha* *n* Return the Laguerre polynomial of degree n with parameter alpha * float *alpha* @@ -447,11 +495,11 @@ * int *n* Degree of the polynomial - - __::math::special::hermite__ *n* + - __::math::special::hermite__ *n* Return the Hermite polynomial of degree n * int *n* @@ -461,12 +509,12 @@ 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\]" + 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 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 @@ -82,78 +82,98 @@ [__::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::group\-rank__ *args*](#38) -[__::math::statistics::test\-Wilcoxon__ *sample\_a* *sample\_b*](#39) -[__::math::statistics::spearman\-rank__ *sample\_a* *sample\_b*](#40) -[__::math::statistics::spearman\-rank\-extended__ *sample\_a* *sample\_b*](#41) -[__::math::statistics::kernel\-density__ *data* opt *\-option value* \.\.\.](#42) -[__::math::statistics::bootstrap__ *data* *sampleSize* ?numberSamples?](#43) -[__::math::statistics::wasserstein\-distance__ *prob1* *prob2*](#44) -[__::math::statistics::kl\-divergence__ *prob1* *prob2*](#45) -[__::math::statistics::logistic\-model__ *xdata* *ydata*](#46) -[__::math::statistics::logistic\-probability__ *coeffs* *x*](#47) -[__::math::statistics::tstat__ *dof* ?alpha?](#48) -[__::math::statistics::mv\-wls__ *wt1* *weights\_and\_values*](#49) -[__::math::statistics::mv\-ols__ *values*](#50) -[__::math::statistics::pdf\-normal__ *mean* *stdev* *value*](#51) -[__::math::statistics::pdf\-lognormal__ *mean* *stdev* *value*](#52) -[__::math::statistics::pdf\-exponential__ *mean* *value*](#53) -[__::math::statistics::pdf\-uniform__ *xmin* *xmax* *value*](#54) -[__::math::statistics::pdf\-gamma__ *alpha* *beta* *value*](#55) -[__::math::statistics::pdf\-poisson__ *mu* *k*](#56) -[__::math::statistics::pdf\-chisquare__ *df* *value*](#57) -[__::math::statistics::pdf\-student\-t__ *df* *value*](#58) -[__::math::statistics::pdf\-gamma__ *a* *b* *value*](#59) -[__::math::statistics::pdf\-beta__ *a* *b* *value*](#60) -[__::math::statistics::pdf\-weibull__ *scale* *shape* *value*](#61) -[__::math::statistics::pdf\-gumbel__ *location* *scale* *value*](#62) -[__::math::statistics::pdf\-pareto__ *scale* *shape* *value*](#63) -[__::math::statistics::pdf\-cauchy__ *location* *scale* *value*](#64) -[__::math::statistics::cdf\-normal__ *mean* *stdev* *value*](#65) -[__::math::statistics::cdf\-lognormal__ *mean* *stdev* *value*](#66) -[__::math::statistics::cdf\-exponential__ *mean* *value*](#67) -[__::math::statistics::cdf\-uniform__ *xmin* *xmax* *value*](#68) -[__::math::statistics::cdf\-students\-t__ *degrees* *value*](#69) -[__::math::statistics::cdf\-gamma__ *alpha* *beta* *value*](#70) -[__::math::statistics::cdf\-poisson__ *mu* *k*](#71) -[__::math::statistics::cdf\-beta__ *a* *b* *value*](#72) -[__::math::statistics::cdf\-weibull__ *scale* *shape* *value*](#73) -[__::math::statistics::cdf\-gumbel__ *location* *scale* *value*](#74) -[__::math::statistics::cdf\-pareto__ *scale* *shape* *value*](#75) -[__::math::statistics::cdf\-cauchy__ *location* *scale* *value*](#76) -[__::math::statistics::cdf\-F__ *nf1* *nf2* *value*](#77) -[__::math::statistics::empirical\-distribution__ *values*](#78) -[__::math::statistics::random\-normal__ *mean* *stdev* *number*](#79) -[__::math::statistics::random\-lognormal__ *mean* *stdev* *number*](#80) -[__::math::statistics::random\-exponential__ *mean* *number*](#81) -[__::math::statistics::random\-uniform__ *xmin* *xmax* *number*](#82) -[__::math::statistics::random\-gamma__ *alpha* *beta* *number*](#83) -[__::math::statistics::random\-poisson__ *mu* *number*](#84) -[__::math::statistics::random\-chisquare__ *df* *number*](#85) -[__::math::statistics::random\-student\-t__ *df* *number*](#86) -[__::math::statistics::random\-beta__ *a* *b* *number*](#87) -[__::math::statistics::random\-weibull__ *scale* *shape* *number*](#88) -[__::math::statistics::random\-gumbel__ *location* *scale* *number*](#89) -[__::math::statistics::random\-pareto__ *scale* *shape* *number*](#90) -[__::math::statistics::random\-cauchy__ *location* *scale* *number*](#91) -[__::math::statistics::histogram\-uniform__ *xmin* *xmax* *limits* *number*](#92) -[__::math::statistics::incompleteGamma__ *x* *p* ?tol?](#93) -[__::math::statistics::incompleteBeta__ *a* *b* *x* ?tol?](#94) -[__::math::statistics::estimate\-pareto__ *values*](#95) -[__::math::statistics::filter__ *varname* *data* *expression*](#96) -[__::math::statistics::map__ *varname* *data* *expression*](#97) -[__::math::statistics::samplescount__ *varname* *list* *expression*](#98) -[__::math::statistics::subdivide__](#99) -[__::math::statistics::plot\-scale__ *canvas* *xmin* *xmax* *ymin* *ymax*](#100) -[__::math::statistics::plot\-xydata__ *canvas* *xdata* *ydata* *tag*](#101) -[__::math::statistics::plot\-xyline__ *canvas* *xdata* *ydata* *tag*](#102) -[__::math::statistics::plot\-tdata__ *canvas* *tdata* *tag*](#103) -[__::math::statistics::plot\-tline__ *canvas* *tdata* *tag*](#104) -[__::math::statistics::plot\-histogram__ *canvas* *counts* *limits* *tag*](#105) +[__::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: @@ -432,15 +452,15 @@ 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\] + test-anova-F 0.05 $A $B $C + # + # Or equivalently: + # + test-anova-F 0.05 [list $A $B $C] * float *alpha* \- Significance level @@ -477,11 +497,11 @@ 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\] + 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* @@ -778,25 +798,48 @@ * list *args* \- Two or more lists of data - - __::math::statistics::group\-rank__ *args* + - __::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* + - __::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 + the sample sizes are both larger than 10\.\) Returns the value of this statistic\. * list *sample\_a* \- List of data comprising the first sample @@ -803,11 +846,11 @@ * list *sample\_b* \- List of data comprising the second sample - - __::math::statistics::spearman\-rank__ *sample\_a* *sample\_b* + - __::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\. @@ -817,11 +860,11 @@ * list *sample\_b* \- Second list of data - - __::math::statistics::spearman\-rank\-extended__ *sample\_a* *sample\_b* + - __::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 @@ -834,11 +877,11 @@ * list *sample\_b* \- Second list of data - - __::math::statistics::kernel\-density__ *data* opt *\-option value* \.\.\. + - __::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\. @@ -876,11 +919,11 @@ + __\-kernel__ *function* Kernel to be used \(One of: gaussian, cosine, epanechnikov, uniform, triangular, biweight, logistic; default: gaussian\) - - __::math::statistics::bootstrap__ *data* *sampleSize* ?numberSamples? + - __::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\. @@ -895,11 +938,11 @@ * int *numberSamples* Number of samples \(default: 1\) - - __::math::statistics::wasserstein\-distance__ *prob1* *prob2* + - __::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\. @@ -914,11 +957,11 @@ * list *prob2* List of values for the second histogram/probability density - - __::math::statistics::kl\-divergence__ *prob1* *prob2* + - __::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\. @@ -936,11 +979,11 @@ * list *prob2* List of values for the second histogram/probability density - - __::math::statistics::logistic\-model__ *xdata* *ydata* + - __::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\. @@ -951,11 +994,11 @@ * list *ydata* List of successes or failures corresponding to each value in *xdata*\. - - __::math::statistics::logistic\-probability__ *coeffs* *x* + - __::math::statistics::logistic\-probability__ *coeffs* *x* Calculate the probability of success for the value *x* given the coefficients of the logistic model\. * list *coeffs* @@ -979,24 +1022,24 @@ Note: These procedures depend on the math::linearalgebra package\. *Description of the procedures* - - __::math::statistics::tstat__ *dof* ?alpha? + - __::math::statistics::tstat__ *dof* ?alpha? Returns the value of the t\-distribution t\* satisfying - P\(t\*\) = 1 \- alpha/2 - P\(\-t\*\) = alpha/2 + 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\) + ( 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\. @@ -1006,22 +1049,22 @@ * float *alpha* Confidence level of the t\-distribution\. Defaults to 0\.05\. - - __::math::statistics::mv\-wls__ *wt1* *weights\_and\_values* + - __::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 + y = b0 + b1 * x1 + b2 * x2 ... + bN * xN + error and each point satisfies - yi = b0 \+ b1 \* xi1 \+ b2 \* xi2 \+ \.\.\. \+ bN \* xiN \+ Residual\_i + yi = b0 + b1 * xi1 + b2 * xi2 + ... + bN * xiN + Residual_i The procedure returns a list with the following elements: * The r\-squared statistic @@ -1043,47 +1086,47 @@ 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* + - __::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\\\]" - \} + # 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: @@ -1130,11 +1173,11 @@ - List of random values with the given distribution \(random\-\*\) The following procedures have been implemented: - - __::math::statistics::pdf\-normal__ *mean* *stdev* *value* + - __::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* @@ -1147,11 +1190,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::pdf\-lognormal__ *mean* *stdev* *value* + - __::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* @@ -1164,11 +1207,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::pdf\-exponential__ *mean* *value* + - __::math::statistics::pdf\-exponential__ *mean* *value* Return the probability of a given value for an exponential distribution with given mean\. * float *mean* @@ -1177,11 +1220,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::pdf\-uniform__ *xmin* *xmax* *value* + - __::math::statistics::pdf\-uniform__ *xmin* *xmax* *value* Return the probability of a given value for a uniform distribution with given extremes\. * float *xmin* @@ -1194,11 +1237,48 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::pdf\-gamma__ *alpha* *beta* *value* + - __::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* @@ -1211,11 +1291,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::pdf\-poisson__ *mu* *k* + - __::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* @@ -1224,11 +1304,11 @@ * int *k* \- Number of occurences - - __::math::statistics::pdf\-chisquare__ *df* *value* + - __::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* @@ -1237,11 +1317,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::pdf\-student\-t__ *df* *value* + - __::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* @@ -1250,11 +1330,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::pdf\-gamma__ *a* *b* *value* + - __::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* @@ -1267,11 +1347,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::pdf\-beta__ *a* *b* *value* + - __::math::statistics::pdf\-beta__ *a* *b* *value* Return the probability of a given value for a Beta distribution with given shape parameters * float *a* @@ -1284,11 +1364,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::pdf\-weibull__ *scale* *shape* *value* + - __::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* @@ -1301,11 +1381,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::pdf\-gumbel__ *location* *scale* *value* + - __::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* @@ -1318,11 +1398,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::pdf\-pareto__ *scale* *shape* *value* + - __::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* @@ -1335,11 +1415,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::pdf\-cauchy__ *location* *scale* *value* + - __::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\. @@ -1353,11 +1433,65 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::cdf\-normal__ *mean* *stdev* *value* + - __::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\. @@ -1371,11 +1505,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::cdf\-lognormal__ *mean* *stdev* *value* + - __::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\. @@ -1389,11 +1523,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::cdf\-exponential__ *mean* *value* + - __::math::statistics::cdf\-exponential__ *mean* *value* Return the cumulative probability of a given value for an exponential distribution with given mean\. * float *mean* @@ -1402,11 +1536,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::cdf\-uniform__ *xmin* *xmax* *value* + - __::math::statistics::cdf\-uniform__ *xmin* *xmax* *value* Return the cumulative probability of a given value for a uniform distribution with given extremes\. * float *xmin* @@ -1419,11 +1553,46 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::cdf\-students\-t__ *degrees* *value* + - __::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* @@ -1432,11 +1601,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::cdf\-gamma__ *alpha* *beta* *value* + - __::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* @@ -1449,11 +1618,11 @@ * float *value* \- Value for which the cumulative probability is required - - __::math::statistics::cdf\-poisson__ *mu* *k* + - __::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* @@ -1462,11 +1631,11 @@ * int *k* \- Number of occurences - - __::math::statistics::cdf\-beta__ *a* *b* *value* + - __::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* @@ -1479,11 +1648,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::cdf\-weibull__ *scale* *shape* *value* + - __::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* @@ -1496,11 +1665,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::cdf\-gumbel__ *location* *scale* *value* + - __::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* @@ -1513,11 +1682,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::cdf\-pareto__ *scale* *shape* *value* + - __::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* @@ -1530,11 +1699,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::cdf\-cauchy__ *location* *scale* *value* + - __::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* @@ -1547,11 +1716,11 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::cdf\-F__ *nf1* *nf2* *value* + - __::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* @@ -1564,21 +1733,77 @@ * float *value* \- Value for which the probability is required - - __::math::statistics::empirical\-distribution__ *values* + - __::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* + - __::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* @@ -1591,11 +1816,11 @@ * int *number* \- Number of values to be returned - - __::math::statistics::random\-lognormal__ *mean* *stdev* *number* + - __::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* @@ -1608,11 +1833,11 @@ * int *number* \- Number of values to be returned - - __::math::statistics::random\-exponential__ *mean* *number* + - __::math::statistics::random\-exponential__ *mean* *number* Return a list of "number" random values satisfying an exponential distribution with given mean\. * float *mean* @@ -1621,11 +1846,11 @@ * int *number* \- Number of values to be returned - - __::math::statistics::random\-uniform__ *xmin* *xmax* *number* + - __::math::statistics::random\-uniform__ *xmin* *xmax* *number* Return a list of "number" random values satisfying a uniform distribution with given extremes\. * float *xmin* @@ -1638,11 +1863,46 @@ * int *number* \- Number of values to be returned - - __::math::statistics::random\-gamma__ *alpha* *beta* *number* + - __::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* @@ -1655,11 +1915,11 @@ * int *number* \- Number of values to be returned - - __::math::statistics::random\-poisson__ *mu* *number* + - __::math::statistics::random\-poisson__ *mu* *number* Return a list of "number" random values satisfying a Poisson distribution with given mean\. * float *mu* @@ -1668,11 +1928,11 @@ * int *number* \- Number of values to be returned - - __::math::statistics::random\-chisquare__ *df* *number* + - __::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* @@ -1681,11 +1941,11 @@ * int *number* \- Number of values to be returned - - __::math::statistics::random\-student\-t__ *df* *number* + - __::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* @@ -1694,11 +1954,11 @@ * int *number* \- Number of values to be returned - - __::math::statistics::random\-beta__ *a* *b* *number* + - __::math::statistics::random\-beta__ *a* *b* *number* Return a list of "number" random values satisfying a Beta distribution with given shape parameters\. * float *a* @@ -1711,11 +1971,11 @@ * int *number* \- Number of values to be returned - - __::math::statistics::random\-weibull__ *scale* *shape* *number* + - __::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* @@ -1728,11 +1988,11 @@ * int *number* \- Number of values to be returned - - __::math::statistics::random\-gumbel__ *location* *scale* *number* + - __::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* @@ -1745,11 +2005,11 @@ * int *number* \- Number of values to be returned - - __::math::statistics::random\-pareto__ *scale* *shape* *number* + - __::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* @@ -1762,11 +2022,11 @@ * int *number* \- Number of values to be returned - - __::math::statistics::random\-cauchy__ *location* *scale* *number* + - __::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* @@ -1779,11 +2039,65 @@ * int *number* \- Number of values to be returned - - __::math::statistics::histogram\-uniform__ *xmin* *xmax* *limits* *number* + - __::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* @@ -1799,17 +2113,17 @@ * int *number* \- Total number of "observations" in the histogram - - __::math::statistics::incompleteGamma__ *x* *p* ?tol? + - __::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 + 1 / x p-1 + P(p,x) = -------- | dt exp(-t) * t + Gamma(p) / 0 * float *x* \- Value of x \(limit of the integral\) @@ -1819,11 +2133,11 @@ * float *tol* \- Required tolerance \(default: 1\.0e\-9\) - - __::math::statistics::incompleteBeta__ *a* *b* *x* ?tol? + - __::math::statistics::incompleteBeta__ *a* *b* *x* ?tol? Evaluate the incomplete Beta integral * float *a* @@ -1839,28 +2153,65 @@ * float *tol* \- Required tolerance \(default: 1\.0e\-9\) - - __::math::statistics::estimate\-pareto__ *values* + - __::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* + - __::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)__\)\. @@ -1874,11 +2225,11 @@ * string *expression* \- Logical expression using the variable name - - __::math::statistics::map__ *varname* *data* *expression* + - __::math::statistics::map__ *varname* *data* *expression* Return a list consisting of the data that are transformed via the expression\. * string *varname* @@ -1891,11 +2242,11 @@ * string *expression* \- Expression to be used to transform \(map\) the data - - __::math::statistics::samplescount__ *varname* *list* *expression* + - __::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* @@ -1908,19 +2259,19 @@ * string *expression* \- Logical expression to test the data \(defaults to "true"\)\. - - __::math::statistics::subdivide__ + - __::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* + - __::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* @@ -1941,11 +2292,11 @@ * float *ymax* \- Maximum y value - - __::math::statistics::plot\-xydata__ *canvas* *xdata* *ydata* *tag* + - __::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* @@ -1962,11 +2313,11 @@ * string *tag* \- Tag to give to the plotted data \(defaults to xyplot\) - - __::math::statistics::plot\-xyline__ *canvas* *xdata* *ydata* *tag* + - __::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* @@ -1983,11 +2334,11 @@ * string *tag* \- Tag to give to the plotted data \(defaults to xyplot\) - - __::math::statistics::plot\-tdata__ *canvas* *tdata* *tag* + - __::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 @@ -2003,11 +2354,11 @@ * string *tag* \- Tag to give to the plotted data \(defaults to xyplot\) - - __::math::statistics::plot\-tline__ *canvas* *tdata* *tag* + - __::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* @@ -2020,11 +2371,11 @@ * string *tag* \- Tag to give to the plotted data \(defaults to xyplot\) - - __::math::statistics::plot\-histogram__ *canvas* *counts* *limits* *tag* + - __::math::statistics::plot\-histogram__ *canvas* *counts* *limits* *tag* Create a simple histogram in the given canvas * widget *canvas* @@ -2074,117 +2425,117 @@ # 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 - \# + # 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\} \{ + # + # Two auxiliary procs + # + proc pause {time} { set wait 0 - after \[expr \{$time\*1000\}\] \{set ::wait 1\} + 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 - \# + } + + 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 + 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 + 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\] + 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 + .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 + 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 + 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 + 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\}\]" + 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\. 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,11 +1,11 @@ [//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 -Redistribution permitted under the terms of the Open Publication License ) -[//000000004]: # (math::calculus::symdiff\(n\) 1\.0\.1 tcllib "Symbolic differentiation for Tcl") +[//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 | 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\}\} + 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 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 @@ -130,22 +130,22 @@ These commands are identical to the MD4 equivalent commands\. # EXAMPLES - % md4::md4 \-hex "Tcl does MD4" + % md4::md4 -hex "Tcl does MD4" 858da9b31f57648a032230447bd15f25 - % md4::hmac \-hex \-key Sekret "Tcl does MD4" + % md4::hmac -hex -key Sekret "Tcl does MD4" c324088e5752872689caedf2a0464758 - % set tok \[md4::MD4Init\] + % set tok [md4::MD4Init] ::md4::1 % md4::MD4Update $tok "Tcl " % md4::MD4Update $tok "does " % md4::MD4Update $tok "MD4" - % md4::Hex \[md4::MD4Final $tok\] + % md4::Hex [md4::MD4Final $tok] 858da9b31f57648a032230447bd15f25 # REFERENCES 1. Rivest, R\., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992\. 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 @@ -140,22 +140,22 @@ These commands are identical to the MD5 equivalent commands\. # EXAMPLES - % md5::md5 \-hex "Tcl does MD5" + % md5::md5 -hex "Tcl does MD5" 8AAC1EE01E20BB347104FABB90310433 - % md5::hmac \-hex \-key Sekret "Tcl does MD5" + % md5::hmac -hex -key Sekret "Tcl does MD5" 35BBA244FD56D3EDF5F3C47474DACB5D - % set tok \[md5::MD5Init\] + % set tok [md5::MD5Init] ::md5::1 % md5::MD5Update $tok "Tcl " % md5::MD5Update $tok "does " % md5::MD5Update $tok "MD5" - % md5::Hex \[md5::MD5Final $tok\] + % md5::Hex [md5::MD5Final $tok] 8AAC1EE01E20BB347104FABB90310433 # REFERENCES 1. Rivest, R\., "The MD5 Message\-Digest Algorithm", RFC 1321, MIT and RSA Data 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 @@ -94,12 +94,12 @@ $1$01234567$b5lh2mHyD2PdJjFfALlEz1 % md5crypt::aprcrypt password 01234567 $apr1$01234567$IXBaQywhAhc0d75ZbaSDp/ - % md5crypt::md5crypt password \[md5crypt::salt\] - $1$dFmvyRmO$T\.V3OmzqeEf3hqJp2WFcb\. + % 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 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,10 +1,10 @@ [//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 tcllib "Mime") +[//000000004]: # (mime\(n\) 1\.6\.2 tcllib "Mime")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.5 -package require mime ?1\.6? +package require mime ?1\.6\.2? [__::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) @@ -161,22 +161,22 @@ 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\] + 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" + uplevel #0 $callback "end" Alternatively, if an error occurs, the callback is invoked as: - uplevel \#0 $callback \[list "error" reason\] + 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 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 @@ -177,24 +177,24 @@ __[md4](\.\./md4/md4\.md)__, __[sha1](\.\./sha1/sha1\.md)__, and __[ripemd160](\.\./ripemd/ripemd160\.md)__\. # EXAMPLE - proc send\_simple\_message \{recipient email\_server subject body\} \{ + proc send_simple_message {recipient email_server subject body} { package require smtp package require mime - set token \[mime::initialize \-canonical text/plain \\\\ - \-string $body\] + set token [mime::initialize -canonical text/plain \ + -string $body] mime::setheader $token Subject $subject - smtp::sendmessage $token \\\\ - \-recipients $recipient \-servers $email\_server + 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\." + 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\. @@ -213,13 +213,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... 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)\) 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 @@ -55,15 +55,15 @@ - __::multiplexer::create__ The __create__ command creates a new multiplexer 'instance'\. For example: - set mp \[::multiplexer::create\] + set mp [::multiplexer::create] This instance can then be manipulated like so: - $\{mp\}::Init 35100 + ${mp}::Init 35100 - __$\{multiplexer\_instance\}::Init__ *port* This starts the multiplexer listening on the specified port\. 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,12 +1,12 @@ [//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\) -Copyright © 200? Various \(http://wiki\.tcl\.tk/1489\) -Copyright © 2010 Documentation, Andreas Kupries) -[//000000004]: # (namespacex\(n\) 0\.2 tcllib "Namespace utility commands") +[//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 | [ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.4 -package require ncgi ?1\.4\.3? +package require ncgi ?1\.4\.4? [__::ncgi::cookie__ *cookie*](#1) [__::ncgi::decode__ *str*](#2) [__::ncgi::empty__ *name*](#3) [__::ncgi::exists__ *name*](#4) @@ -300,30 +300,30 @@ Uploading a file HTML: - + Path:
Name:
- TCL: upload\.cgi - \#\!/usr/local/bin/tclsh + TCL: upload.cgi + #!/usr/local/bin/tclsh ::ncgi::parse - set filedata \[::ncgi::value filedata\] - set filedesc \[::ncgi::value filedesc\] + set filedata [::ncgi::value filedata] + set filedesc [::ncgi::value filedesc] - puts " File uploaded at $filedesc " + puts " File uploaded at $filedesc " set filename /www/images/$filedesc - set fh \[open $filename w\] - puts \-nonewline $fh $filedata + 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 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 @@ -68,12 +68,12 @@ 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::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*\. @@ -141,20 +141,20 @@ 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\} \{ + 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 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 @@ -350,19 +350,19 @@ # 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\] + 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\] + Date: [clock format [clock seconds] -format "%a, %d % + b %y %H:%M:%S GMT" -gmt true] Test message body" # Bugs, Ideas, Feedback 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 @@ -146,27 +146,27 @@ - __::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 + % 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 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,10 +1,10 @@ [//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\.2 tcllib "oauth") +[//000000004]: # (oauth\(n\) 1\.0\.3 tcllib "oauth")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.5 -package require oauth ?1\.0\.2? +package require oauth ?1\.0\.3? [__::oauth::config__](#1) [__::oauth::config__ ?*options*\.\.\.?](#2) [__::oauth::header__ *baseURL* ?*postQuery*?](#3) [__::oauth::query__ *baseURL* ?*postQuery*?](#4) @@ -71,13 +71,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... your own application code ... # Commands - __::oauth::config__ @@ -155,18 +155,18 @@ 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\} + ::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::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\. @@ -183,57 +183,57 @@ 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\} + % 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"\} + % 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 + id_str => 158812437 name => Un Librepensador - screen\_name => AbiertaMente + 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 \{\}\} + 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 + 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 + 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 + 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 + follow_request_sent => false notifications => false # Bugs, Ideas, Feedback This document, and the package it describes, will undoubtedly contain bugs and 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 @@ -56,39 +56,39 @@ The __oo::meta__ package provides a data registry service for TclOO classes\. # Usage - oo::class create animal \{ + oo::class create animal { meta set biodata animal: 1 - \} - oo::class create mammal \{ + } + oo::class create mammal { superclass animal meta set biodata mammal: 1 - \} - oo::class create cat \{ + } + oo::class create cat { superclass mammal meta set biodata diet: carnivore - \} + } cat create felix - puts \[felix meta dump biodata\] + 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 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\} + 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 @@ -109,24 +109,24 @@ - __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 $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 $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__ @@ -135,11 +135,11 @@ 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\] + 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 @@ -159,13 +159,13 @@ 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 \{ + 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__\. 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 @@ -78,21 +78,21 @@ 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 \{ + 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 + } + 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 @@ -105,16 +105,16 @@ purpose\. The difference is that it cannot be used in the class definition itself\. Example: - % oo::class create Foo \{ - method bar \{z\} \{ + % oo::class create Foo { + method bar {z} { classvariable x y - return \[incr x $z\],\[incr y\] - \} - \} + return [incr x $z],[incr y] + } + } ::Foo % Foo create a ::a % Foo create b ::b @@ -122,11 +122,11 @@ 2,1 % a bar 3 5,2 % b bar 7 12,3 - % b bar \-1 + % b bar -1 11,4 % a bar 0 11,5 - __link__ *method*\.\.\. @@ -141,18 +141,18 @@ 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\. + # 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 {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 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*\.\.\.? @@ -163,18 +163,18 @@ Syntax and results are like for __oo::class__\. Example: - % oo::class create example \{ + % oo::class create example { self mixin singleton - method foo \{\} \{self\} - \} + method foo {} {self} + } ::example - % \[example new\] foo + % [example new] foo ::oo::Obj22 - % \[example new\] foo + % [example new] foo ::oo::Obj22 # AUTHORS Donal Fellows, Andreas Kupries 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 @@ -71,15 +71,15 @@ - __::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" + % 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" + % 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\. 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 @@ -76,11 +76,11 @@ 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\. + or rather, not calling it anymore. This command updates the cross\-references and which nonterminals are now undefined\. - __::page::util::peg::flatten__ *treequery* *tree* 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 @@ -97,20 +97,36 @@ 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"\. 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\. + 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\. @@ -203,10 +219,14 @@ 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 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 @@ -156,25 +156,25 @@ 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 + => 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 + => 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 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,11 +1,11 @@ [//000000001]: # (png \- Image manipulation) [//000000002]: # (Generated from file 'png\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004, Code: Aaron Faupell -Copyright © 2004, Doc: Andreas Kupries ) -[//000000004]: # (png\(n\) 0\.3 tcllib "Image manipulation") +[//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 | 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*? @@ -256,32 +256,32 @@ 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 \.\.\. + tls::init -cafile /path/to/ca/cert -keyfile ... - \# Create secured pop3 channel - pop3::open \-socketcmd tls::socket \\\\ + # 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 \.\.\. + tls::init -cafile /path/to/ca/cert -keyfile ... - \# Create secured pop3 channel - pop3::open \-stls 1 \\\\ + # 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 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,11 +1,11 @@ [//000000001]: # (pop3d \- Tcl POP3 Server Package) [//000000002]: # (Generated from file 'pop3d\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002\-2009 Andreas Kupries -Copyright © 2005 Reinhard Max ) -[//000000004]: # (pop3d\(n\) 1\.1\.0 tcllib "Tcl POP3 Server Package") +[//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 | References 1. [RFC 1939](http://www\.rfc\-editor\.org/rfc/rfc1939\.txt) 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,10 +1,10 @@ [//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\.11 tcllib "The The Proper Rational API for C to Tool Command Language Module") +[//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 | SYNOPSIS package require TclOO 1\.0 -package require practcl 0\.11 - -[__CPUTS__ *varname* *body* ?*body*\.\.\.?](#1) -[__practcl::\_isdirectory__ *path*](#2) -[__practcl::object__ *parent* ?*keyvaluelist*?](#3) -[__practcl::library__ ?*keyvaluelist*?](#4) -[__practcl::exe__ ?*keyvaluelist*?](#5) -[__practcl::product__ *parent* ?*keyvaluelist*?](#6) -[__practcl::cheader__ *parent* ?*keyvaluelist*?](#7) -[__practcl::csource__ *parent* ?*keyvaluelist*?](#8) -[__practcl::module__ *parent* ?*keyvaluelist*?](#9) -[__practcl::submodule__ *parent* ?*keyvaluelist*?](#10) + +[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\. -# 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 +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\. 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,9 +1,9 @@ [//000000001]: # (profiler \- Tcl Profiler) [//000000002]: # (Generated from file 'profiler\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (profiler\(n\) 0\.3 tcllib "Tcl Profiler") +[//000000003]: # (profiler\(n\) 0\.5 tcllib "Tcl Profiler")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.3 -package require profiler ?0\.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::sortFunctions__ *key*](#7) +[__::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, @@ -120,11 +122,25 @@ 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* + - __::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 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 @@ -229,45 +229,45 @@ ## 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 ; + 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 + 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\} - \} - \} - \} - \} + 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) 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 @@ -187,28 +187,28 @@ # Usage To use a converter do - \# Get the converter \(single command here, not class\) - package require the\-converter\-package + # Get the converter (single command here, not class) + package require the-converter-package - \# Perform the conversion - set serial \[theconverter convert $thegrammartext\] + # Perform the conversion + set serial [theconverter convert $thegrammartext] - \.\.\. process the result \.\.\. + ... process the result ... To use a plugin __FOO__ do - \# Get an import plugin manager + # 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\] + # Run the plugin, and the converter inside. + set serial [I import serial $thegrammartext FOO] - \.\.\. process the result \.\.\. + ... 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\. @@ -298,36 +298,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -457,15 +457,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -130,78 +130,78 @@ ## 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 ; + 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" : \{ + { + "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\} - \} + 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 @@ -293,36 +293,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -452,15 +452,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -556,52 +556,52 @@ # 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 + 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 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 @@ -148,30 +148,30 @@ # 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\] + 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 \.\.\. + 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 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\] + set parser [pt::peg::interp] $parser use $grammar - set ast \[$parser parse $channel\] + set ast [$parser parse $channel] $parser destroy - \.\.\. process the abstract syntax tree \.\.\. + ... 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\. @@ -223,45 +223,45 @@ ## 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 ; + 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 + 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\} - \} - \} - \} - \} + 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) @@ -395,15 +395,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -189,21 +189,21 @@ overwriting the existing definition\. This is the assignment operator for grammars\. This operation is in effect equivalent to - *objectName* __deserialize =__ \[*source* __serialize__\] + > *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__\] + > *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 @@ -473,36 +473,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -632,15 +632,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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,10 +1,10 @@ [//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 tcllib "Parser Tools") +[//000000004]: # (pt::peg::export\(n\) 1\.0\.1 tcllib "Parser Tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.5 package require snit -package require configuration +package require struct::map package require pt::peg package require pluginmgr -package require pt::peg::export ?1? +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) @@ -316,36 +316,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -475,15 +475,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -186,54 +186,54 @@ ## 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 ; + 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\} + 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 \{ + $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\} - \} + } + $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 - \} + 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\. @@ -323,36 +323,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -482,15 +482,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -205,78 +205,78 @@ ## 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 ; + 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" : \{ + { + "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\} - \} + 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 @@ -368,36 +368,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -527,15 +527,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -153,128 +153,128 @@ 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 + 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 + 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 <\- \!\. ; - - \# \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 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 ; + 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 ; + 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 @@ -365,36 +365,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -524,15 +524,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -167,78 +167,78 @@ ## 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 ; + 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" : \{ + { + "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\} - \} + 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 @@ -330,36 +330,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -489,15 +489,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -95,128 +95,128 @@ 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 + 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 + 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 <\- \!\. ; - - \# \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 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 ; + 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 ; + 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 @@ -307,36 +307,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -466,15 +466,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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,10 +1,10 @@ [//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 tcllib "Parser Tools") +[//000000004]: # (pt::peg::import\(n\) 1\.0\.1 tcllib "Parser Tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.5 +package require Tcl 8\.5 package require snit -package require configuration +package require fileutil::paths package require pt::peg package require pluginmgr -package require pt::peg::import ?1? +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) @@ -334,36 +335,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -493,15 +494,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -176,78 +176,78 @@ ## 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 ; + 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" : \{ + { + "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\} - \} + 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 @@ -339,36 +339,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -498,15 +498,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -105,128 +105,128 @@ 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 + 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 + 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 <\- \!\. ; - - \# \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 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 ; + 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 ; + 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 @@ -317,36 +317,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -476,15 +476,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -220,45 +220,45 @@ ## 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 ; + 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 + 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\} - \} - \} - \} - \} + 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) @@ -392,15 +392,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -79,11 +79,11 @@ ## Basic structure The general outline of a textual PEG is - PEG <> \(<>\) + PEG <> (<>) <> END; *Note*: We are using text in double angle\-brackets as place\-holders for things not yet explained\. @@ -101,32 +101,32 @@ 1. zero or more letters, digits, underscores, or colons\. Or, in formal textual notation: - \(\[\_:\] / \) \(\[\_:\] / \)\* + ([_:] / ) ([_:] / )* Examples of names: Hello ::world - \_:submarine55\_ + _:submarine55_ Examples of text which are *not* names: 12 - \.bogus + .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 @@ -150,49 +150,49 @@ 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\. + # 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: @@ -221,40 +221,40 @@ 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\. + # 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\] + [_:] + [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 @@ -264,14 +264,14 @@ 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 + \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\. @@ -286,17 +286,17 @@ ## 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__ @@ -333,128 +333,128 @@ 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 + 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 + 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 <\- \!\. ; - - \# \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 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 ; + 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 ; + 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 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 @@ -78,21 +78,21 @@ 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 | + 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\. 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 @@ -206,54 +206,54 @@ ## 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 ; + 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\} + 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 \{ + $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\} - \} + } + $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 - \} + 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\. @@ -343,36 +343,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -502,15 +502,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -399,36 +399,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -558,15 +558,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -235,78 +235,78 @@ ## 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 ; + 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" : \{ + { + "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\} - \} + 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 @@ -398,36 +398,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -557,15 +557,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -181,779 +181,779 @@ ## 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 ; + 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' + # -*- text -*- + # Parsing Expression Grammar 'TEMPLATE'. + # Generated for unknown, from file 'TEST' - \# - \# Grammar Start Expression - \# + # + # Grammar Start Expression + # <
>: - call sym\_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 - - \# - \# + # + # 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\. @@ -1043,36 +1043,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -1202,15 +1202,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -174,128 +174,128 @@ 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 + 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 + 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 <\- \!\. ; - - \# \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 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 ; + 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 ; + 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 @@ -386,36 +386,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -545,15 +545,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -248,11 +248,12 @@ 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__ package\. + 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 @@ -371,36 +372,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -530,15 +531,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -247,36 +247,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -406,15 +406,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -239,15 +239,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -438,15 +438,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -133,76 +133,76 @@ 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 ; + 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 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 + 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 + 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 channel [open $input r] - set parser \[calculator\] - set ast \[$parser parse $channel\] + set parser [calculator] + set ast [$parser parse $channel] $parser destroy close $channel - \.\.\. now process the returned abstract syntax tree \.\.\. + ... 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\} - \} - \} - \} - \} + 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 + 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\. 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 @@ -547,326 +547,326 @@ - *objectName* __si:void\_state\_push__ This method combines - i\_loc\_push - i\_error\_clear - i\_error\_push + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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* @@ -899,12 +899,12 @@ - *objectName* __si:next\_xdigit__ These methods all combine - i\_input\_next $msg - i:fail\_return + i_input_next $msg + i:fail_return with the appropriate __i\_test\_xxx__ instruction\. Parsers use them for handling atomic expressions\. # Bugs, Ideas, Feedback 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 @@ -50,11 +50,11 @@ 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__\-based parser packages\. +__[OO](\.\./\.\./\.\./\.\./index\.md\#oo)__\-based parser packages\. It is a supporting package in the Core Layer of Parser Tools\. ![](\.\./\.\./\.\./\.\./image/arch\_core\_support\.png) @@ -61,12 +61,13 @@ # 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*\. + *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 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 @@ -206,34 +206,34 @@ # 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 \.\.\. + # 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 + # Get an export plugin manager package require pt::peg::export pt::peg::export E - \# Provide a configuration - E configuration set \.\.\. + # Provide a configuration + E configuration set ... - \# Run the plugin, and the converter inside\. - set result \[E export serial $grammarserial FOO\] + # Run the plugin, and the converter inside. + set result [E export serial $grammarserial FOO] - \.\.\. process the result \.\.\. + ... 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\. @@ -323,36 +323,36 @@ ## 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 ; + 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\} - \} + 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\. @@ -482,15 +482,15 @@ ## Example Assuming the parsing expression shown on the right\-hand side of the rule - Expression <\- Term \(AddOp Term\)\* + Expression <- Term (AddOp Term)* then its canonical serialization \(except for whitespace\) is - \{x \{n Term\} \{\* \{x \{n AddOp\} \{n Term\}\}\}\} + {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 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 @@ -101,25 +101,25 @@ 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 + % set keydata [binary format H* 0123456789abcdef] + % rc4::rc4 -hex -key $keydata HelloWorld 3cf1ae8b7f1c670b612f - % rc4::rc4 \-hex \-key $keydata \[binary format H\* 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\] + 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\} \{ + proc ::Finish {myState data} { DoStuffWith $myState $data - \} - rc4::rc4 \-in $socket \-command \[list ::Finish $ApplicationState\] + } + rc4::rc4 -in $socket -command [list ::Finish $ApplicationState] # AUTHORS Pat Thoyts 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,11 +1,11 @@ [//000000001]: # (rcs \- RCS low level utilities) [//000000002]: # (Generated from file 'rcs\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005, Andreas Kupries -Copyright © 2005, Colin McCormack ) -[//000000004]: # (rcs\(n\) 2\.0\.2 tcllib "RCS low level utilities") +[//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 | 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 @@ -274,15 +274,15 @@ 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\. + {{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\. + }} {a 11 {They both may be called deep and profound. Deeper and more profound, - The door of all subtleties\!\}\}\} + 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 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 @@ -387,47 +387,47 @@ 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\] + ::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\}\} \{ + ::report::defstyle captionedtable {{n 1}} { simpletable - topdata set \[data get\] - topcapsep set \[top get\] + 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 + % # ... 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 + +---+-------------------+-------+-------+--------+ + |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 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 @@ -112,22 +112,22 @@ 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\] + 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 \{ + 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\} + 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 @@ -139,17 +139,17 @@ 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\] + 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 @@ -459,51 +459,51 @@ # Examples Yahoo Geo: - set ygeo\(parse\) \{ - url http://wherein\.yahooapis\.com/v1/document + set ygeo(parse) { + url http://wherein.yahooapis.com/v1/document method post - body \{ arg documentContent \} - \} + body { arg documentContent } + } ygeo::parse "san jose ca" - \# "san jose ca" will be interpreted as if it were specified as the \-documentContent option + # "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\] + 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 + set delicious(updated) { + url https://api.del.icio.us/v1/posts/update auth basic - \} + } - rest::create\_interface flickr + rest::create_interface flickr - flickr::basic\_auth username password + 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 + 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: @@ -557,13 +557,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... 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 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 @@ -138,22 +138,22 @@ These commands are identical to the RIPEMD128 equivalent commands\. # EXAMPLES - % ripemd::ripemd128 \-hex "Tcl does RIPEMD\-128" + % ripemd::ripemd128 -hex "Tcl does RIPEMD-128" 3cab177bae65205d81e7978f63556c63 - % ripemd::hmac128 \-hex \-key Sekret "Tcl does RIPEMD\-128" + % ripemd::hmac128 -hex -key Sekret "Tcl does RIPEMD-128" b359dc5971a05beea0be7b106b30e389 - % set tok \[ripemd::RIPEMD128Init\] + % set tok [ripemd::RIPEMD128Init] ::ripemd::1 % ripemd::RIPEMD128Update $tok "Tcl " % ripemd::RIPEMD128Update $tok "does " - % ripemd::RIPEMD128Update $tok "RIPEMD\-128" - % ripemd::Hex \[ripemd::RIPEMD128Final $tok\] + % ripemd::RIPEMD128Update $tok "RIPEMD-128" + % ripemd::Hex [ripemd::RIPEMD128Final $tok] 3cab177bae65205d81e7978f63556c63 # REFERENCES 1. H\. Dobbertin, A\. Bosselaers, B\. Preneel, "RIPEMD\-160, a strengthened 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 @@ -130,22 +130,22 @@ These commands are identical to the RIPEMD160 equivalent commands\. # EXAMPLES - % ripemd::ripemd160 \-hex "Tcl does RIPEMD\-160" + % ripemd::ripemd160 -hex "Tcl does RIPEMD-160" 0829dea75a1a7074c702896723fe37763481a0a7 - % ripemd::hmac160 \-hex \-key Sekret "Tcl does RIPEMD\-160" + % ripemd::hmac160 -hex -key Sekret "Tcl does RIPEMD-160" bf0c927231733686731dddb470b64a9c23f7f53b - % set tok \[ripemd::RIPEMD160Init\] + % set tok [ripemd::RIPEMD160Init] ::ripemd::1 % ripemd::RIPEMD160Update $tok "Tcl " % ripemd::RIPEMD160Update $tok "does " - % ripemd::RIPEMD160Update $tok "RIPEMD\-160" - % ripemd::Hex \[ripemd::RIPEMD160Final $tok\] + % ripemd::RIPEMD160Update $tok "RIPEMD-160" + % ripemd::Hex [ripemd::RIPEMD160Final $tok] 0829dea75a1a7074c702896723fe37763481a0a7 # REFERENCES 1. H\. Dobbertin, A\. Bosselaers, B\. Preneel, "RIPEMD\-160, a strengthened 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 @@ -66,13 +66,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... your own application code ... # AUTHORS Pat Thoyts 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 @@ -285,32 +285,32 @@ 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\] + 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\]'" + 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\} - \} + if {!$more_steps} {break} + } SASL::cleanup $ctx - \} + } # REFERENCES 1. Myers, J\. "Simple Authentication and Security Layer \(SASL\)", RFC 2222, October 1997\. 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,10 +1,10 @@ [//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\.3 tcllib "SHA\-x Message\-Digest Algorithm") +[//000000004]: # (sha1\(n\) 2\.0\.4 tcllib "SHA\-x Message\-Digest Algorithm")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.2 -package require sha1 ?2\.0\.3? +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) @@ -156,16 +156,16 @@ 285a6a91c45a9066bf39fcf24425796ef0b2a8bf % sha1::hmac Sekret "Tcl does SHA1" ae6251fa51b95b18cba2be95eb031d07475ff03c - % set tok \[sha1::SHA1Init\] + % set tok [sha1::SHA1Init] ::sha1::1 % sha1::SHA1Update $tok "Tcl " % sha1::SHA1Update $tok "does " % sha1::SHA1Update $tok "SHA1" - % sha1::Hex \[sha1::SHA1Final $tok\] + % sha1::Hex [sha1::SHA1Final $tok] 285a6a91c45a9066bf39fcf24425796ef0b2a8bf # REFERENCES 1. "Secure Hash Standard", National Institute of Standards and Technology, 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,10 +1,10 @@ [//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\.3 tcllib "SHA\-x Message\-Digest Algorithm") +[//000000004]: # (sha256\(n\) 1\.0\.4 tcllib "SHA\-x Message\-Digest Algorithm")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.2 -package require sha256 ?1\.0\.3? +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) @@ -167,16 +167,16 @@ 0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789 % sha2::hmac Sekret "Tcl does SHA256" 4f9352c64d655e8a36abe73e6163a9d7a54039877c1c92ec90b07d48d4e854e0 - % set tok \[sha2::SHA256Init\] + % set tok [sha2::SHA256Init] ::sha2::1 % sha2::SHA256Update $tok "Tcl " % sha2::SHA256Update $tok "does " % sha2::SHA256Update $tok "SHA256" - % sha2::Hex \[sha2::SHA256Final $tok\] + % sha2::Hex [sha2::SHA256Final $tok] 0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789 # REFERENCES 1. "Secure Hash Standard", National Institute of Standards and Technology, 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 @@ -63,17 +63,17 @@ 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\)\}\] + 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 + result -4.9112922923 x -0.181647676593 y 0.155743646974 # PROCEDURES The package defines the following auxiliary procedures: @@ -174,17 +174,17 @@ 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 - \} - \}\] + 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\. @@ -196,33 +196,33 @@ 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 - \} + 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\} \{ + 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\]\}\] - \} + 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 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 @@ -68,38 +68,38 @@ 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 \{ + # + # 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 + 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\]" + } + puts [getOption reportfile] "Correlation: [::math::statistics::corr $means $medians]" - \} \-trials 100 \-samples 10 \-verbose 1 \-columns \{Mean Median\} + } -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\. 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,10 +1,10 @@ [//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\.1 tcllib "Tcl Simulation Tools") +[//000000004]: # (simulation::random\(n\) 0\.4 tcllib "Tcl Simulation Tools")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl ?8\.4? -package require simulation::random 0\.1 +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\_Exponential__ *min* *mean*](#5) -[__::simulation::random::prng\_Normal__ *mean* *stdev*](#6) -[__::simulation::random::prng\_Pareto__ *min* *steep*](#7) -[__::simulation::random::prng\_Gumbel__ *min* *f*](#8) -[__::simulation::random::prng\_chiSquared__ *df*](#9) -[__::simulation::random::prng\_Disk__ *rad*](#10) -[__::simulation::random::prng\_Sphere__ *rad*](#11) -[__::simulation::random::prng\_Ball__ *rad*](#12) -[__::simulation::random::prng\_Rectangle__ *length* *width*](#13) -[__::simulation::random::prng\_Block__ *length* *width* *depth*](#14) +[__::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 @@ -61,11 +63,11 @@ - coordinates of points uniformly spread inside a sphere or a rectangle For example: - set p \[::simulation::random::prng\_Normal \-1\.0 10\.0\] + 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\. @@ -115,11 +117,40 @@ * float *max* Maximum number that will be generated - - __::simulation::random::prng\_Exponential__ *min* *mean* + - __::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* @@ -128,11 +159,11 @@ * float *mean* Mean value for the numbers - - __::simulation::random::prng\_Normal__ *mean* *stdev* + - __::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* @@ -141,11 +172,11 @@ * float *stdev* Standard deviation - - __::simulation::random::prng\_Pareto__ *min* *steep* + - __::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* @@ -154,27 +185,27 @@ * float *steep* Steepness of the distribution - - __::simulation::random::prng\_Gumbel__ *min* *f* + - __::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\)\)\) + 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* + - __::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\. @@ -182,38 +213,38 @@ Degrees of freedom The package defines the following public procedures for random point sets: - - __::simulation::random::prng\_Disk__ *rad* + - __::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* + - __::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* + - __::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* + - __::simulation::random::prng\_Rectangle__ *length* *width* Create a command \(PRNG\) that generates \(x,y\)\-coordinates for points uniformly spread over a rectangle\. * float *length* @@ -222,11 +253,11 @@ * float *width* Width of the rectangle \(y\-direction\) - - __::simulation::random::prng\_Block__ *length* *width* *depth* + - __::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* 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 @@ -104,13 +104,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... your own application code ... # COMMANDS - __::smtpd::start__ ?*myaddr*? ?*port*? @@ -117,11 +117,11 @@ 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\] + 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 @@ -199,20 +199,20 @@ 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\!" - \} - \} + 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\. + 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\. @@ -221,17 +221,17 @@ 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" - \} + 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 @@ -246,30 +246,30 @@ 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\] + 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"\] + 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 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 @@ -230,16 +230,16 @@ 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" \} + 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\!" + $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\. @@ -252,12 +252,12 @@ __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\!" + $type a b "Hello, world!" + $type {a b} "Hello, world!" In Snit 2\.2, the second form is invalid\. * __typeconstructor__ *body* @@ -308,24 +308,24 @@ array is also visible\. If the *name* consists of two or more tokens, Snit handles it specially: - method \{a b\} \{\} \{ \.\.\. \} + 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\!" + $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"\} - \} + % snit::type dog { + method {tail wag} {} {return "Wag, wag"} + method {tail droop} {} {return "Droop, droop"} + } ::dog % dog spot ::spot % spot tail wag Wag, wag @@ -345,12 +345,12 @@ __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\!" + $self a b "Hello, world!" + $self {a b} "Hello, world!" In Snit 2\.2, the second form is invalid\. * __option__ *namespec* ?*defaultValue*? @@ -363,30 +363,30 @@ 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\} + 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\} + 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\) + 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\. @@ -411,16 +411,16 @@ 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 + 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\} + 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 @@ -441,14 +441,14 @@ 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\) - \} + 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* @@ -462,14 +462,14 @@ 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 - \} + 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* @@ -483,16 +483,16 @@ 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\." - \} - \} + 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* @@ -508,21 +508,21 @@ 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\} \{ + 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 \{\} \{\} + 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 @@ -574,13 +574,13 @@ delegate method wag to tail is roughly equivalent to this explicitly defined method: - method wag \{args\} \{ + 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\. @@ -667,11 +667,11 @@ __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 + 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* @@ -688,17 +688,17 @@ 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\} \{ + method ConfigureMethod {option value} { $comp configure $option $value - \} + } - method CgetMethod \{option\} \{ - return \[$comp cget $option\] - \} + 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*\. @@ -723,22 +723,22 @@ 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 + 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 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 @@ -747,13 +747,13 @@ delegate typemethod lostdogs to pound is roughly equivalent to this explicitly defined method: - typemethod lostdogs \{args\} \{ + 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\. @@ -830,11 +830,11 @@ 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 + 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*? @@ -848,21 +848,21 @@ 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 + 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 + 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 @@ -951,40 +951,40 @@ __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 - \} + 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 - \} + 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 - \} + 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 - \} + 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__ @@ -1111,15 +1111,15 @@ 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 \{ \.\.\. \} + snit::type dog { ... } - set mydog \[dog create %AUTO%\] - set mydog \[dog %AUTO%\] - set mydog \[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\. @@ -1370,13 +1370,13 @@ 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 [list $self dosomething myargument] - $button configure \-command \[mymethod 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\.\.\.*? @@ -1386,13 +1386,13 @@ 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 [list $type dosomething myargument] - $button configure \-command \[mytypemethod 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__\. @@ -1403,13 +1403,13 @@ 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 [list ${type}::dosomething myargument] - $button configure \-command \[myproc 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 @@ -1441,13 +1441,13 @@ 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\.\.\. + install myComp using myObjType $self.myComp args... - set myComp \[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\. @@ -1540,47 +1540,47 @@ 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 \{ + snit::type dog { component mytail - constructor \{args\} \{ - set mytail \[tail %AUTO% \-partof $self\] + constructor {args} { + set mytail [tail %AUTO% -partof $self] $self configurelist $args - \} + } - method wag \{\} \{ + method wag {} { $mytail wag - \} - \} - - snit::type tail \{ - option \-length 5 - option \-partof - method wag \{\} \{ return "Wag, wag, 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 \{ + snit::type dog { component mytail - constructor \{args\} \{ - install mytail using tail %AUTO% \-partof $self + constructor {args} { + install mytail using tail %AUTO% -partof $self $self configurelist $args - \} + } - method wag \{\} \{ + 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)\. @@ -1587,18 +1587,18 @@ 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 \{ + snit::type dog { delegate method wag to mytail - constructor \{args\} \{ - install mytail using tail %AUTO% \-partof $self + 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__ @@ -1605,20 +1605,20 @@ component\. If desired, all otherwise unknown methods can be delegated to a specific component: - snit::type dog \{ - delegate method \* to mytail + snit::type dog { + delegate method * to mytail - constructor \{args\} \{ - set mytail \[tail %AUTO% \-partof $self\] + constructor {args} { + set mytail [tail %AUTO% -partof $self] $self configurelist $args - \} + } - method bark \{ return "Bark, bark, bark\!" \} - \} + 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\. @@ -1677,11 +1677,11 @@ 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 \{ \.\.\. \} + 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 @@ -1704,41 +1704,41 @@ 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 + -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 - \# \.\.\. - \} + 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 + -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 @@ -1745,31 +1745,31 @@ __[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 - \# \.\.\. - \} + 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 - \# \.\.\. - \} + 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\. @@ -1779,18 +1779,18 @@ 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 + 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"\. @@ -1797,28 +1797,28 @@ __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\] + 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 @@ -1848,24 +1848,24 @@ 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 - \# - \} - \#\.\.\. - \} + 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\] + 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 @@ -1880,28 +1880,28 @@ 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 + snit::widget mywidget { + delegate option -background to myComp - constructor \{args\} \{ - set myComp \[text $win\.text \-foreground black\] - \} - \} + 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 + snit::widget mywidget { + delegate option -background to myComp - constructor \{args\} \{ - install myComp using text $win\.text \-foreground black - \} - \} + 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__\. @@ -1933,42 +1933,42 @@ 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 \{ + snit::type dog { variable mood happy - method getmood \{\} \{ + method getmood {} { return $mood - \} + } - method setmood \{newmood\} \{ + 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\} \{ + snit::macro property {name initValue} { variable $name $initValue - method get$name \{\} "return $name" + method get$name {} "return $name" - method set$name \{value\} "set $name \\$value" - \} + 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 \{ + 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__\. @@ -1976,15 +1976,15 @@ 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::macro mypkg::property {name initValue} { ... } - snit::type dog \{ + snit::type dog { mypkg::property mood happy - \} + } This leaves the global namespace open for application authors\. ## Validation Types @@ -1995,45 +1995,45 @@ 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\!\) + 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 + 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 + 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 - \} + 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\. @@ -2135,26 +2135,26 @@ 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\} + 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\} - \} + option -numbers -type { + snit::listtype -type {snit::integer -min 5} + } Instead, define the subtype explicitly: - snit::integer gt4 \-min 5 + snit::integer gt4 -min 5 - snit::type mytype \{ - option \-numbers \-type \{snit::listtype \-type gt4\} - \} + snit::type mytype { + option -numbers -type {snit::listtype -type gt4} + } - __snit::pixels__ __validate__ ?*value*? - __snit::pixels__ *name* ?*option* *value*\.\.\.? @@ -2231,84 +2231,84 @@ 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, \.\.\." - \} + 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" - \} + 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 + } + + # 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\. + # 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\. + # 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 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 @@ -562,15 +562,15 @@ ## 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 + 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 + 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, @@ -595,13 +595,13 @@ - 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 + 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\. @@ -612,11 +612,11 @@ 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 + 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 @@ -623,21 +623,21 @@ 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 configure} {tag args} { ... } - method \{tag cget\} \{tag option\} \{\.\.\.\} + 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 + $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 @@ -700,11 +700,11 @@ 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\]::\* + 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\. @@ -743,13 +743,13 @@ 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\!" + # 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\. @@ -771,13 +771,13 @@ 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 \{ - \# \.\.\. - \} + % snit::type dog { + # ... + } ::dog % This definition defines a new command \(__::dog__, in this case\) that can be used to define dog objects\. @@ -803,13 +803,13 @@ 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 \{ - \# \.\.\.\. - \} + % snit::type dog { + # .... + } ::dog % dog create spot ::spot % @@ -816,13 +816,13 @@ 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 \{ - \# \.\.\.\. - \} + % snit::type dog { + # .... + } ::dog % dog spot ::spot % @@ -829,45 +829,45 @@ 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 + % snit::type dog { + option -breed mongrel + option -color brown - method bark \{\} \{ return "$self barks\." \} - \} + method bark {} { return "$self barks." } + } ::dog - % dog create spot \-breed dalmation \-color spotted + % dog create spot -breed dalmation -color spotted ::spot - % spot cget \-breed + % spot cget -breed dalmation - % spot cget \-color + % 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\. + ::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 \{ \.\.\. \} + % snit::type dog { ... } ::dog - % set d \[dog spot \-breed dalmation \-color spotted\] + % set d [dog spot -breed dalmation -color spotted] ::spot - % $d cget \-breed + % $d cget -breed dalmation % $d bark - ::spot barks\. + ::spot barks. % If you prefer this style, you might prefer to have Snit generate the instance's name automatically\. @@ -874,24 +874,24 @@ ## 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 \{ \.\.\. \} + % snit::type dog { ... } ::dog - % set d \[dog %AUTO%\] + % set d [dog %AUTO%] ::dog2 % $d bark - ::dog2 barks\. + ::dog2 barks. % The __%AUTO%__ keyword can be embedded in a longer string: - % set d \[dog obj\_%AUTO%\] - ::obj\_dog4 + % set d [dog obj_%AUTO%] + ::obj_dog4 % $d bark - ::obj\_dog4 barks\. + ::obj_dog4 barks. % ## Can types be renamed? Tcl's __rename__ command renames other commands\. It's a common technique in @@ -917,18 +917,18 @@ - 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\] + .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\] + .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\. @@ -955,30 +955,30 @@ 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 \{ \.\.\. \} + % snit::type dog { ... } ::dog % dog spot ::spot % spot bark - ::spot barks\. + ::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 \{ \.\.\. \} + % snit::type dog { ... } ::dog % dog spot ::spot % spot bark - ::spot barks\. + ::spot barks. % dog destroy % spot bark invalid command name "spot" % dog fido invalid command name "dog" @@ -996,19 +996,19 @@ 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\." - \} - \} + % 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\. @@ -1024,13 +1024,13 @@ simulated dog through its paces: % dog spot ::spot % spot bark - ::spot barks\. + ::spot barks. % spot chase cat - ::spot chases 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 @@ -1038,26 +1038,26 @@ 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\]" - \} - \} + % 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 barks. % spot chase cat - ::spot chases cat\. ::spot barks\. + ::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: @@ -1078,28 +1078,28 @@ 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\} \{ \.\.\. \} + snit::widget mytext { + method {tag configure} {tag args} { ... } - method \{tag cget\} \{tag option\} \{\.\.\.\} - \} + 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 + % 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? @@ -1113,25 +1113,25 @@ 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\]" - \} - \} + % 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\. + ::fido chases cat. ::fido barks. % ## Are there any limitations on instance method arguments? Method argument lists are defined just like normal Tcl @@ -1150,15 +1150,15 @@ ## What is $type? The implicit argument __type__ contains the fully qualified name of the object's type: - % snit::type thing \{ - method mytype \{\} \{ + % snit::type thing { + method mytype {} { return $type - \} - \} + } + } ::thing % thing something ::something % something mytype ::thing @@ -1170,15 +1170,15 @@ 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 \{\} \{ + % snit::type thing { + method myself {} { return $self - \} - \} + } + } ::thing % thing mutt ::mutt % mutt myself ::mutt @@ -1192,23 +1192,23 @@ 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 \{\} \{ + % snit::type thing { + method myNameSpace {} { return $selfns - \} - \} + } + } ::thing % thing jeff ::jeff % jeff myNameSpace - ::thing::Snit\_inst3 + ::thing::Snit_inst3 % rename jeff mutt % mutt myNameSpace - ::thing::Snit\_inst3 + ::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\. @@ -1237,24 +1237,24 @@ 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\] + 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\] - \#\.\.\. - \} - \} + % 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 @@ -1269,17 +1269,17 @@ __$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\] - \#\.\.\. - \} - \} + % 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; @@ -1307,28 +1307,28 @@ 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\!" - \} + 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 \{ + snit::type mytype { + # Define array variable "greetings" + variable greetings -array { formal "Good Evening" - casual "Howdy\!" - \} - \} + 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 @@ -1371,29 +1371,29 @@ 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 \{\} \{ + snit::type dog { + constructor {} { variable mood set mood happy - \} + } - method setmood \{newMood\} \{ + method setmood {newMood} { variable mood set mood $newMood - \} + } - method getmood \{\} \{ + 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\. @@ -1408,21 +1408,21 @@ 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 \{ + snit::widget mywidget { variable labeltext "" - constructor \{args\} \{ - \# \.\.\. - - label $win\.label \-textvariable \[myvar 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 @@ -1445,16 +1445,16 @@ 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 - \} + 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\. @@ -1461,16 +1461,16 @@ 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 - \} + 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\. @@ -1480,13 +1480,13 @@ 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 + % dog spot -breed beagle -color "mottled" -akc 1 -shots 1 ::spot - % dog fido \-shots 1 + % 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\. @@ -1497,49 +1497,49 @@ ## How can a client retrieve an option's value? Retrieve option values using the __cget__ method: - % spot cget \-color + % spot cget -color mottled - % fido cget \-breed + % 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 + % fido configure -color dun -breed "Arctic Boar Hound" + % fido cget -color dun - % fido cget \-breed + % 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\} + % set features [list -color dun -breed "Arctic Boar Hound"] + -color dun -breed {Arctic Boar Hound} % fido configurelist $features - % fido cget \-color + % fido cget -color dun - % fido cget \-breed + % 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 + % 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 + % fido cget -breed Arctic Boar Hound % The results are the same\. @@ -1546,36 +1546,36 @@ ## 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 + % snit::type dog { + option -weight 10 - method gainWeight \{\} \{ - set wt \[$self cget \-weight\] + method gainWeight {} { + set wt [$self cget -weight] incr wt - $self configure \-weight $wt - \} - \} + $self configure -weight $wt + } + } ::dog % dog fido ::fido - % fido cget \-weight + % fido cget -weight 10 % fido gainWeight - % fido cget \-weight + % 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\) - \} + 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 @@ -1592,20 +1592,20 @@ 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 - \} + % snit::type dog { + option -breed -default mongrel -readonly yes + option -shots -default no + } ::dog - % dog fido \-breed retriever + % dog fido -breed retriever ::fido - % fido configure \-shots yes - % fido configure \-breed terrier - option \-breed can only be set at instance creation + % 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\. @@ -1618,17 +1618,17 @@ 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 + snit::type dog { + option -color -default brown -cgetmethod GetOption - method GetOption \{option\} \{ - return $options\($option\) - \} - \} + 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? @@ -1643,17 +1643,17 @@ 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 + snit::type dog { + option -color -default brown -configuremethod SetOption - method SetOption \{option value\} \{ - set options\($option\) $value - \} - \} + 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, @@ -1673,23 +1673,23 @@ 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\\"" - \} - \} - \} + % 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 + % 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\. @@ -1710,30 +1710,30 @@ 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\!" - \} + 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 \{ + snit::type mytype { + # Define typearray variable "greetings" + typevariable greetings -array { formal "Good Evening" - casual "Howdy\!" - \} - \} + 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 @@ -1766,21 +1766,21 @@ 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 \{ + snit::widget mywidget { typevariable labeltext "" - constructor \{args\} \{ - \# \.\.\. - - label $win\.label \-textvariable \[mytypevar 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\. @@ -1787,13 +1787,13 @@ 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 \{ + snit::type mytype { typevariable myvariable - \} + } set ::mytype::myvariable "New Value" # TYPE METHODS @@ -1806,18 +1806,18 @@ ## 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 + snit::type dog { + # List of pedigreed dogs typevariable pedigreed - typemethod pedigreedDogs \{\} \{ + 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 @@ -1829,27 +1829,27 @@ 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 + snit::type dog { + option -pedigreed 0 - \# List of pedigreed dogs + # List of pedigreed dogs typevariable pedigreed - typemethod pedigreedDogs \{\} \{ + typemethod pedigreedDogs {} { return $pedigreed - \} + } - \# \.\.\. - \} + # ... + } - dog spot \-pedigreed 1 + dog spot -pedigreed 1 dog fido - foreach dog \[dog pedigreedDogs\] \{ \.\.\. \} + 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__\. @@ -1880,28 +1880,28 @@ ## 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\] \{ \.\.\. \} - \} - \} + 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 + 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)\. @@ -1922,17 +1922,17 @@ ## 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\} \{ \.\.\. \} + 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 @@ -1948,22 +1948,22 @@ ## 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\] - \} - \} + 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 @@ -1984,17 +1984,17 @@ 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 \{ + % snit::type mytype { typevariable lookupTable - typeconstructor \{ - array set lookupTable \{key value\.\.\.\} - \} - \} + typeconstructor { + array set lookupTable {key value...} + } + } # CONSTRUCTORS ## What is a constructor? @@ -2013,29 +2013,29 @@ 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 + % snit::type dog { + option -akc 0 - typevariable akcList \{\} + typevariable akcList {} - constructor \{args\} \{ + constructor {args} { $self configurelist $args - if \{$options\(\-akc\)\} \{ + if {$options(-akc)} { lappend akcList $self - \} - \} + } + } - typemethod akclist \{\} \{ + typemethod akclist {} { return $akcList - \} - \} + } + } ::dog - % dog spot \-akc 1 + % dog spot -akc 1 ::spot % dog fido ::fido % dog akclist ::spot @@ -2044,15 +2044,15 @@ ## 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\} \{ + 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 @@ -2063,25 +2063,25 @@ 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 \{ + % snit::type dog { variable breed - option \-color brown - option \-akc 0 + option -color brown + option -akc 0 - constructor \{theBreed args\} \{ + constructor {theBreed args} { set breed $theBreed $self configurelist $args - \} + } - method breed \{\} \{ return $breed \} - \} + method breed {} { return $breed } + } ::dog - % dog spot dalmatian \-color spotted \-akc 1 + % dog spot dalmatian -color spotted -akc 1 ::spot % spot breed dalmatian The drawback is that this syntax is non\-standard, and may limit the @@ -2118,35 +2118,35 @@ 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 + snit::type dog { + option -akc 0 - typevariable akcList \{\} + typevariable akcList {} - constructor \{args\} \{ + constructor {args} { $self configurelist $args - if \{$options\(\-akc\)\} \{ + if {$options(-akc)} { lappend akcList $self - \} - \} - - destructor \{ - set ndx \[lsearch $akcList $self\] - - if \{$ndx \!= \-1\} \{ - set akcList \[lreplace $akcList $ndx $ndx\] - \} - \} - - typemethod akclist \{\} \{ + } + } + + 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\. @@ -2182,23 +2182,23 @@ 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 \{ + snit::type dog { component tail - constructor \{args\} \{ + constructor {args} { $self configurelist $args - set tail \[tail %AUTO%\] - \} + set tail [tail %AUTO%] + } - destructor \{ - catch \{$tail destroy\} - \} - \} + destructor { + catch {$tail destroy} + } + } # COMPONENTS ## What is a component? @@ -2221,23 +2221,23 @@ the component is created\. For example, suppose your __dog__ object creates a __tail__ object \(the better to wag with, no doubt\): - snit::type dog \{ + snit::type dog { component mytail - constructor \{args\} \{ - \# Create and save the component's command - set mytail \[tail %AUTO% \-partof $self\] + constructor {args} { + # Create and save the component's command + set mytail [tail %AUTO% -partof $self] $self configurelist $args - \} + } - method wag \{\} \{ + 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 @@ -2273,46 +2273,46 @@ 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 \{ + snit::type dog { component mytail - constructor \{args\} \{ - set mytail \[tail %AUTO% \-partof $self\] + constructor {args} { + set mytail [tail %AUTO% -partof $self] $self configurelist $args - \} + } - destructor \{ - catch \{$mytail destroy\} - \} + destructor { + catch {$mytail destroy} + } delegate method wagtail to mytail as wag - method bark \{\} \{ - return "$self barked\." - \} - \} + method bark {} { + return "$self barked." + } + } - snit::type tail \{ + snit::type tail { component mydog - option \-partof \-readonly yes + option -partof -readonly yes - constructor \{args\} \{ + constructor {args} { $self configurelist $args - set mydog $options\(\-partof\) - \} - - method wag \{\} \{ - return "Wag, wag\." - \} - - method pull \{\} \{ + 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\. @@ -2321,19 +2321,19 @@ 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 \{ + snit::type dog { component mytail - constructor \{args\} \{ - \# set mytail \[tail %AUTO% \-partof $self\] - install mytail using tail %AUTO% \-partof $self + 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) @@ -2358,19 +2358,19 @@ 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 tail { ... } - snit::type dog \{ + snit::type dog { delegate method wag to mytail - constructor \{\} \{ + 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__\. @@ -2387,11 +2387,11 @@ 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 + install mytail using tail ${selfns}::mytail Make sure you pick a unique name within the instance namespace\. ## Must I destroy the components I own? @@ -2424,20 +2424,20 @@ 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 + 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\. @@ -2466,17 +2466,17 @@ 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 veterinarian { ... } - snit::type dog \{ + 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 @@ -2483,19 +2483,19 @@ __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 veterinarian { ... } - snit::type dog \{ + snit::type dog { typecomponent vet - typeconstructor \{ - set vet \[veterinarian %AUTO%\] - \} - \} + 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)\. @@ -2508,33 +2508,33 @@ 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 \{ + snit::type dog { variable mytail - option \-taillength \-configuremethod SetTailOption \-cgetmethod GetTailOption + option -taillength -configuremethod SetTailOption -cgetmethod GetTailOption - method SetTailOption \{option value\} \{ + method SetTailOption {option value} { $mytail configure $option $value - \} + } - method GetTailOption \{option\} \{ + method GetTailOption {option} { $mytail cget $option - \} + } - method wag \{\} \{ + method wag {} { $mytail wag - \} + } - constructor \{args\} \{ - install mytail using tail %AUTO% \-partof $self + 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 @@ -2551,26 +2551,26 @@ information about component names\.\) For example, here's a much better way to delegate the __dog__ object's __wag__ method: - % snit::type dog \{ + % snit::type dog { delegate method wag to mytail - constructor \{\} \{ + constructor {} { install mytail using tail %AUTO% - \} - \} + } + } ::dog - % snit::type tail \{ - method wag \{\} \{ return "Wag, wag, wag\."\} - \} + % snit::type tail { + method wag {} { return "Wag, wag, wag."} + } ::tail % dog spot ::spot % spot wag - Wag, wag, 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\. @@ -2586,37 +2586,37 @@ 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 \{ + snit::type dog { delegate method wagtail to mytail as wag - constructor \{args\} \{ - install mytail using tail %AUTO% \-partof $self + 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\] - \} - \# \.\.\. - \} + 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 @@ -2630,13 +2630,13 @@ 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\} - \} + 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 @@ -2668,27 +2668,27 @@ 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 + % snit::type dog { + delegate option -length to mytail - constructor \{args\} \{ - install mytail using tail %AUTO% \-partof $self + constructor {args} { + install mytail using tail %AUTO% -partof $self $self configurelist $args - \} - \} + } + } ::dog - % snit::type tail \{ - option \-partof - option \-length 5 - \} + % snit::type tail { + option -partof + option -length 5 + } ::tail - % dog spot \-length 7 + % dog spot -length 7 ::spot - % spot cget \-length + % 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 @@ -2703,18 +2703,18 @@ 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 + snit::type dog { + delegate option -taillength to mytail as -length - constructor \{args\} \{ - set mytail \[tail %AUTO% \-partof $self\] + 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, @@ -2724,25 +2724,25 @@ 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 + 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 \{\} \{ + 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 @@ -2762,23 +2762,23 @@ 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 + 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\. @@ -2785,37 +2785,37 @@ ## 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\} \{ + 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 + snit::type dog { + delegate method {tail *} to mytail - \# \.\.\. - \} + # ... + } # WIDGETS ## What is a snit::widget? @@ -2875,15 +2875,15 @@ __[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 \{ + 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 @@ -2895,15 +2895,15 @@ defines the __\-class__ option\. For example, suppose Tk gets a new widget type called a __prettyframe__: lappend snit::hulltypes prettyframe - snit::widget mywidget \{ + 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 @@ -2915,23 +2915,23 @@ 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\] - - \# \.\.\.\. + 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 @@ -2957,35 +2957,35 @@ 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 \{ + ::snit::widgetadaptor rotext { - constructor \{args\} \{ - \# Create the text widget; turn off its insert cursor - installhull using text \-insertwidth 0 + constructor {args} { + # Create the text widget; turn off its insert cursor + installhull using text -insertwidth 0 - \# Apply any options passed at creation time\. + # 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\. + } + + # 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 - \} + # 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 @@ -3010,18 +3010,18 @@ 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\. + 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 @@ -3091,22 +3091,22 @@ 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 \{ \.\.\. \} + 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 \{ + 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\. @@ -3136,14 +3136,14 @@ 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 + -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? @@ -3151,25 +3151,25 @@ 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 - \# \.\.\. - \} - - \# \.\.\. - \} + % 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 + % 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\. @@ -3176,64 +3176,64 @@ 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 - \# \.\.\. - \} - - \# \.\.\. - \} + % 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 + % 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 + % snit::widget mytext { + delegate option {-padx padX Pad} to text - \# \.\.\. - \} + # ... + } ::mytext - % mytext \.text - \.text - % \.text configure \-padx - \-padx padX Pad 1 1 + % 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 + 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"\. @@ -3247,28 +3247,28 @@ 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\] + 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 @@ -3295,31 +3295,31 @@ 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 + 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 - \# \.\.\. - \} - \# \.\.\. - \} + 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\] + 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 @@ -3326,11 +3326,11 @@ 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\] + 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? @@ -3351,28 +3351,28 @@ 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 + snit::widget mywidget { + delegate option -background to myComp - constructor \{args\} \{ - set myComp \[text $win\.text \-foreground black\] - \} - \} + 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 + snit::widget mywidget { + delegate option -background to myComp - constructor \{args\} \{ - install myComp using text $win\.text \-foreground black - \} - \} + 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__\. @@ -3431,17 +3431,17 @@ 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 + snit::type ::mynamespace::mystringtype { + delegate method * to stringhandler - constructor \{\} \{ + 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\. @@ -3457,17 +3457,17 @@ 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 + snit::type mystring { + delegate typemethod * to stringhandler - typeconstructor \{ + 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__ @@ -3477,21 +3477,21 @@ 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 \{ + 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 @@ -3511,36 +3511,36 @@ ## How can I get rid of the "info" type method? Set the __\-hastypeinfo__ pragma to __no__: - snit::type dog \{ - pragma \-hastypeinfo 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::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::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\. @@ -3555,19 +3555,19 @@ 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 - \#\.\.\. - \} + snit::type dog { + pragma -hastypemethods no + #... + } - \# Creates ::spot + # Creates ::spot dog spot - \# Tries to create an instance called ::create + # Tries to create an instance called ::create dog create spot Pragmas __\-hastypemethods__ and __\-hasinstances__ cannot both be false \(or there'd be nothing left\)\. @@ -3575,23 +3575,23 @@ 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 \{ \.\.\. \} + 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 - \# \.\.\. - \} + 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__\. @@ -3632,71 +3632,71 @@ 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\} - \} + 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 \{\} \{\.\.\.\} - \} - \} + 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 + snit::widget mywidget { + option -background -default white -configuremethod PropagateBackground - method PropagateBackground \{option value\} \{ + 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 - \} + 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 + snit::widget mywidget { + option -background default -white + option -foreground default -black - propagate \-background to \{comp1 comp2 comp3\} - propagate \-foreground to \{comp1 comp2 comp3\} - \} + 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 @@ -3710,19 +3710,19 @@ 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\} - \} + 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 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,12 +1,12 @@ [//000000001]: # (soundex \- Soundex) [//000000002]: # (Generated from file 'soundex\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © ????, Algorithm: Donald E\. Knuth -Copyright © 2003, Documentation: Andreas Kupries -Copyright © 1998, Tcl port: Evan Rempel ) -[//000000004]: # (soundex\(n\) 1\.0 tcllib "Soundex") +[//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 | 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 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 @@ -111,17 +111,17 @@ # 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 + ::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 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 + ::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)\) 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 @@ -78,19 +78,19 @@ \[::unicode::fromstring \\$string\]\]\. Normalizes Tcl string and returns normalized string\. # EXAMPLES - % ::unicode::fromstring "\\u0410\\u0411\\u0412\\u0413" + % ::unicode::fromstring "\u0410\u0411\u0412\u0413" 1040 1041 1042 1043 - % ::unicode::tostring \{49 50 51 52 53\} + % ::unicode::tostring {49 50 51 52 53} 12345 % - % ::unicode::normalize D \{7692 775\} + % ::unicode::normalize D {7692 775} 68 803 775 - % ::unicode::normalizeS KD "\\u1d2c" + % ::unicode::normalizeS KD "\u1d2c" A % # REFERENCES 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 @@ -77,23 +77,23 @@ - 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\. - | / \* \\ | - | / \* / | - | \* /\\ \* / | - | / \\ / | - | / \\/ \* | - | / \* \\ | - | / \* \\ | - \+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\+ + +-----------------+ 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 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,10 +1,10 @@ [//000000001]: # (struct::graph \- Tcl Data Structures) [//000000002]: # (Generated from file 'graph\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002\-2009 Andreas Kupries ) -[//000000004]: # (struct::graph\(n\) 2\.4\.1 tcllib "Tcl Data Structures") +[//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 | SYNOPSIS package require Tcl 8\.4 -package require struct::graph ?2\.4\.1? +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) @@ -196,11 +196,11 @@ *graphName*\. The old contents of *graphName* are deleted by this operation\. This operation is in effect equivalent to - *graphName* __deserialize__ \[*sourcegraph* __serialize__\] + > *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* @@ -210,11 +210,11 @@ object *destgraph*\. The old contents of *destgraph* are deleted by this operation\. This operation is in effect equivalent to - *destgraph* __deserialize__ \[*graphName* __serialize__\] + > *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* @@ -405,12 +405,12 @@ 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\. + __\-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\. @@ -448,10 +448,18 @@ * __\-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*\. @@ -590,13 +598,16 @@ 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: + 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 @@ -726,28 +737,28 @@ 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\. + # 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 @@ -869,6 +880,6 @@ Data structures # COPYRIGHT -Copyright © 2002\-2009 Andreas Kupries +Copyright © 2002\-2009,2019 Andreas Kupries 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,12 +1,12 @@ [//000000001]: # (struct::graph::op \- Tcl Data Structures) [//000000002]: # (Generated from file 'graphops\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008 Alejandro Paz -Copyright © 2008 \(docs\) Andreas Kupries -Copyright © 2009 Michal Antoniewski ) -[//000000004]: # (struct::graph::op\(n\) 0\.11\.3 tcllib "Tcl Data Structures") +[//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 | ) -[//000000004]: # (struct::matrix\(n\) 2\.0\.3 tcllib "Tcl Data Structures") +[//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 | SYNOPSIS package require Tcl 8\.2 -package require struct::matrix ?2\.0\.3? +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) @@ -149,11 +149,11 @@ *matrixName*\. The old contents of *matrixName* are deleted by this operation\. This operation is in effect equivalent to - *matrixName* __deserialize__ \[*sourcematrix* __serialize__\] + > *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 @@ -160,11 +160,11 @@ the object *destmatrix*\. The old contents of *destmatrix* are deleted by this operation\. This operation is in effect equivalent to - *destmatrix* __deserialize__ \[*matrixName* __serialize__\] + > *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 @@ -392,19 +392,19 @@ 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\}\} + # 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\. @@ -477,37 +477,37 @@ 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\}\} + {{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 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\}\} + {{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 + % # ... 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 + +---+-------------------+-------+-------+--------+ + |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 @@ -531,6 +531,6 @@ Data structures # COPYRIGHT -Copyright © 2002\-2013 Andreas Kupries +Copyright © 2002\-2013,2019 Andreas Kupries 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,10 +1,10 @@ [//000000001]: # (struct::matrix\_v1 \- Tcl Data Structures) [//000000002]: # (Generated from file 'matrix1\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002 Andreas Kupries ) -[//000000004]: # (struct::matrix\_v1\(n\) 1\.2\.1 tcllib "Tcl Data Structures") +[//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 | SYNOPSIS package require Tcl 8\.2 -package require struct::matrix ?1\.2\.1? +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) @@ -358,37 +358,37 @@ 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\}\} + {{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 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\}\} + {{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 + % # ... 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 + +---+-------------------+-------+-------+--------+ + |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 @@ -412,6 +412,6 @@ Data structures # COPYRIGHT -Copyright © 2002 Andreas Kupries +Copyright © 2002,2019 Andreas Kupries 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 @@ -295,69 +295,69 @@ 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 + 1. Load the package into an interpreter % package require pool - 0\.1 + 0.1 - 2\. Create a pool object called \`CarPool' with a maximum size of 55 items \(cars\): + 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: + 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: + 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: + 6. Acquired a new car for the pool. Add it as follows: % CarPool add Nissan - 7\. Check whether the pool was adjusted correctly: + 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\." - \} + # 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\." - \} + # 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: + 8. When the car is returned then you can render it available by: % CarPool release Trabant - 9\. When done, you delete the pool\. + 9. When done, you delete the pool. % CarPool destroy - Couldn't destroy \`CarPool' because some items are still allocated\. + Couldn't destroy `CarPool' because some items are still allocated. - Oops, forgot that Mrs\. Swift still occupies a car\. + Oops, forgot that Mrs. Swift still occupies a car. - 10\. We force the destruction of the pool as follows: - % CarPool destroy \-force + 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 @@ -366,30 +366,30 @@ 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\) + # 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\+\] + 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' + # 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\. - \} + # ...... 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 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,10 +1,10 @@ [//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\.1 tcllib "Tcl Data Structures") +[//000000004]: # (struct::record\(n\) 1\.2\.2 tcllib "Tcl Data Structures")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.2 -package require struct::record ?1\.2\.1? +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) @@ -51,39 +61,47 @@ [__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) -[*recordName* __*instanceName|\#auto*__ ?*\-member1 value1 \-member2 value2 \.\.\.*?](#10) -[*instanceName* __cget__ ?*\-member1 \-member2 \.\.\.*?](#11) -[*instanceName* __configure__ ?*\-member1 value1 \-member2 value2 \.\.\.*?](#12) +[*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' 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\. +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 define, hence the +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\. *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 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\. @@ -116,262 +134,274 @@ 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\. + 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\. For example, it would look -like this: +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 \{ + # this is the nested record + record define mynestedrecord { nest1 nest2 - \} + } - \# This is the main record - record define myrecord \{ + # This is the main record + record define myrecord { mem1 mem2 - \{record mynestedrecord mem3\} - \} + {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 \{ + 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* + {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\. - 1. To get a member value, then use the instance built\-in __cget__ method: - - *instanceName* __cget__ \-mem1 - - 1. To get multiple member values, you can specify them all in one command: - - *instanceName* __cget__ \-mem1 \-mem2 - - 1. To get a list of the key/value of all of the members, there are 3 ways: - - \- *instanceName* __cget__ - - \- *instanceName* __configure__ - - \- *instanceName* - - 1. To get a value of a nested member, then use the dot notation: - - *instanceName* __cget__ \-mem3\.nest1 - -*Setting Values* + - *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\. - 1. To set a member value, then use the instance built\-in __configure__ - method: - - *instanceName* __configure__ \-mem1 val1 - - 1. To set multiple member values, you can specify them all in one command: - - *instanceName* __configure__ \-mem1 va1 \-mem2 val2 - - 1. To set a value of a nested member, then use the dot notation: - - *instanceName* __configure__ \-mem3\.nest1 value - -*Alias access* + - *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' 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\. +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 + % # 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 \{\} - % + + % # 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 \.\.\.*? + - *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, where is a unique integer \(starting at 0\) - that is generated\. + 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 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\. + - *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 an good illustration on how to use this +Two examples are provided to give a good illustration on how to use this package\. -*Example 1* +## 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 \{ + ## + ## 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\} + {country USA} phone - \} + } ::locations - % \# Define the main record\. Notice that it uses the location record twice\. - % record define contacts \{ + % # Define the main record. Notice that it uses the location record twice. + % record define contacts { first middle last - \{record locations home\} - \{record locations work\} - \} + {record locations home} + {record locations work} + } ::contacts - % \# Create an instance for the contacts record\. + % # Create an instance for the contacts record. % contacts cont1 ::cont1 - % \# Display some introspection values + % # 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 \{\}\} - % \# + -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 \{\}\} - % \# + -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\] + -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\} + first middle last {record locations home} {record locations work} % record show members contacts - first middle last \{record locations home\} \{record locations work\} + first middle last {record locations home} {record locations work} % -*Example 1* +## Example 2 \- Linked List This next example just illustrates a simple linked list - % \# define a very simple record for linked list - % record define llist \{ + % # define a very simple record for linked list + % record define linkedlist { value next - \} - ::llist - % llist lstart + } + ::linkedlist + % linkedlist 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" + % 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\} - \} + % 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 + % # 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 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,11 +1,11 @@ [//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 -Copyright © 2003\-2012 Andreas Kupries ) -[//000000004]: # (struct::list\(n\) 1\.8\.4 tcllib "Tcl Data Structures") +[//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 | __::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 @@ -240,11 +240,11 @@ 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 + tclsh> ::struct::list assign {a b c d e} foo bar c d e tclsh> set foo a tclsh> set bar b @@ -256,13 +256,13 @@ 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\} + 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 @@ -271,21 +271,21 @@ 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> # squaring all elements in a list - tclsh> proc sqr \{x\} \{expr \{$x\*$x\}\} - tclsh> ::struct::list map \{1 2 3 4 5\} sqr + 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> # 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\} + 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*, @@ -294,23 +294,23 @@ 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> # squaring all elements in a list - tclsh> ::struct::list mapfor x \{1 2 3 4 5\} \{ - expr \{$x \* $x\} - \} + 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> # 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\}\} \{ + 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 @@ -322,14 +322,14 @@ 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> # 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 + 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\. @@ -346,13 +346,13 @@ 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> # removing all odd numbers from the input - tclsh> ::struct::list filterfor x \{1 2 3 4 5\} \{\($x % 2\) == 0\} + 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 @@ -405,13 +405,13 @@ 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 \+ + 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* @@ -449,16 +449,16 @@ *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 [::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 + 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 @@ -476,15 +476,15 @@ 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\}\} + {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 @@ -618,38 +618,38 @@ outer join, combined\. We extend all the joins from two to __n__ tables \(__n__ > 2\) by executing - \(\.\.\.\(\(table1 join table2\) join table3\) \.\.\.\) join tableN + (...((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\} + {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 \{\} \{\}\} + {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\} + {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\} + {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\)\. ADDED embedded/md/tcllib/files/modules/struct/struct_map.md Index: embedded/md/tcllib/files/modules/struct/struct_map.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/struct_map.md @@ -0,0 +1,98 @@ + +[//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\. 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 @@ -196,11 +196,11 @@ *treeName*\. The old contents of *treeName* are deleted by this operation\. This operation is in effect equivalent to - *treeName* __deserialize__ \[*sourcetree* __serialize__\] + > *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 @@ -207,11 +207,11 @@ *desttree*\. The old contents of *desttree* are deleted by this operation\. This operation is in effect equivalent to - *desttree* __deserialize__ \[*treeName* __serialize__\] + > *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 @@ -277,29 +277,29 @@ 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\} \{ + 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\} - \} + } + 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\] + tclsh> lsort [mytree children -all root filter vol] 0 5 - tclsh> lsort \[mytree children \-all root filter vgt40\] + tclsh> lsort [mytree children -all root filter vgt40] 5 - tclsh> lsort \[mytree children root filter vol\] + tclsh> lsort [mytree children root filter vol] 0 - tclsh> puts \(\[lsort \[mytree children root filter vgt40\]\]\) - \(\) + 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 @@ -481,19 +481,19 @@ 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 + +- d + +- a -+ + root -+- b +- e + +- c is - \{root \{\} \{\} a 0 \{\} d 3 \{\} e 3 \{\} b 0 \{\} c 0 \{\}\} + {root {} {} a 0 {} d 3 {} e 3 {} b 0 {} c 0 {}} - The above assumes that none of the nodes have attributes\. + 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 @@ -578,21 +578,21 @@ 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\. + 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 \-\- + 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 @@ -669,16 +669,16 @@ # 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\. + 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 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 @@ -62,12 +62,12 @@ 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\} + % ::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\. @@ -111,21 +111,21 @@ 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\)" - \} + % 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\] \{ + % 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\. @@ -146,12 +146,12 @@ 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 + % ::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 @@ -181,12 +181,12 @@ 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 + % ::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 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 @@ -79,33 +79,33 @@ __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\. + > 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 @@ -112,28 +112,26 @@ 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*\} - - __\}__\] + > 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" - \.\.\. +> __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 @@ -143,55 +141,55 @@ ## 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* \\ - \.\.\. +> 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" \\ - \.\.\. +> 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 \\ - \.\.\. +> 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 \\ - \.\.\. +> 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 \\ - \.\.\. +> 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 @@ -199,18 +197,19 @@ 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 \\ - \.\.\. - __\-__ \{ * - ?\- ? - ?\- ? - ?\.\.\.?* - \} - \.\.\. +> tepam::argument\_dialogbox \\ +>    \.\.\. +>    __\-__ \{ +>       *?\- ?* +>       *?\- ?* +>       *?\.\.\.?* +> +>    \} +>    \.\.\. The following items are classified into this group: - \-frame *list* @@ -223,59 +222,59 @@ An optional frame label can be specified with the *\-label* statement\. Example: - tepam::argument\_dialogbox \\ - \.\.\. - __\-frame__ \{*\-label "Destination address"*\} - \.\.\. +> 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__ \{\} - \.\.\. +> 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__ \{\} - \.\.\. +> 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"*\} - \.\.\. +> 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__ - \.\.\. +> tepam::argument\_dialogbox \\ +>    \.\.\. +>    __\-yscroll__ __auto__ +>    \.\.\. ## Global Custom Data Validation This item group allows specifying global custom checks to validate the entered data\. @@ -283,13 +282,13 @@ - \-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\} +> 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 @@ -318,18 +317,19 @@ 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 \\ - \.\.\. - __\-__ \{ * - ?\- ? - ?\- ? - ?\.\.\.?* - \} - \.\.\. +> 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)\. @@ -341,40 +341,40 @@ - \-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\} +> 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\} +> 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\} +> 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\} +> 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\. @@ -388,32 +388,32 @@ 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\} +> 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\} +> 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\} +> 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* @@ -421,18 +421,18 @@ 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\} +> 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\} +> 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 @@ -439,26 +439,26 @@ *\-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\} +> 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\} +> 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 @@ -468,15 +468,15 @@ 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\}\} +> 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\. @@ -486,48 +486,48 @@ 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"\} +> 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"\} +> 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\} +> 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\} +> tepam::argument\_dialogbox \\ +>    __\-existingdirectory__ \{\-label "Report directory" \-variable ReportDir\} Finally, there is a last group of some other special data entry widgets\. - \-color *list* @@ -534,12 +534,12 @@ 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\} +> 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 @@ -558,14 +558,14 @@ 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\}\} +> 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: @@ -572,40 +572,40 @@ - \-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\} +> 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\} +> 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__\} +> 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__\} +> 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\) @@ -613,14 +613,14 @@ 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__\} \\ +> 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 @@ -635,12 +635,12 @@ 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__\} \\ +> 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 @@ -647,23 +647,23 @@ 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\}__\} +> 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"\} +> 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\. @@ -680,44 +680,44 @@ 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 +> 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\}__ +> 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__\} +> 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\} +> 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* @@ -724,23 +724,23 @@ 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\}\}\}__\} +> 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"__\} +> 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\. @@ -747,12 +747,12 @@ 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__" +> tepam::argument\_dialogbox \\ +>    \-file "\-variable ImageF __\-activedir $pwd__" Finally, there is a last attribute supported by some widgets: - \-height *string* @@ -759,13 +759,13 @@ 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__\} +> 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 @@ -773,20 +773,20 @@ 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" - \} - \} +> *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\. @@ -838,33 +838,33 @@ 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\]\} - \} - \} + 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\} - \} + 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 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 @@ -242,39 +242,39 @@ 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>* +>       *<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>\) @@ -430,80 +430,74 @@ 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\]"* +> 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 \-> +> gen\(TXT,ArgumentString\) mtype 0 1 string \-> *"\-mtype "* - *"\-mtype "* Named arguments can also be optional: + Named arguments can also be optional: - gen\(TXT,ArgumentString\) mtype 1 1 string \-> - - *"\[\-mtype \]"* +> 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\]"* +> 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 +> __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 +> __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 +> __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 +> __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 +> *\# 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 @@ -517,32 +511,33 @@ __[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 +> *\# 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) 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 @@ -132,32 +132,32 @@ 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\]" - \} - \} - *\} +> __[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 @@ -203,93 +203,113 @@ # 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\.* +> __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\!\}* +> __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* +> __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 +> __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\. @@ -316,14 +336,14 @@ 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\} +> __[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\. @@ -348,74 +368,83 @@ 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 +> 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'* +> 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) 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 @@ -108,25 +108,25 @@ 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* - \.\.\. + > __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* - \.\.\. + > __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 @@ -138,14 +138,13 @@ TEPAM uses the term *argument* for the parameters of a procedure\. The following example calls the subcommand __string compare__ with several arguments: - __string compare__ + > __string compare__ *\-nocase \-length 3 "emphasized" "emphasised"* - *\-nocase \-length 3 "emphasized" "emphasised"* The following paragraphs - discuss these different argument types\. + 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 @@ -183,27 +182,26 @@ 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__ + > __string compare__ *\-nocase \-length 3 Water $Text* - *\-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*\. + 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__ + > __pack__ *\.ent1 \.ent2 \-fill x \-expand yes \-side left* - *\.ent1 \.ent2 \-fill x \-expand yes \-side left* This style is referred in the - TEPAM documentation as *unnamed arguments first, named arguments later - style*\. + 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 @@ -211,31 +209,31 @@ - __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" - \} +> __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* @@ -246,21 +244,21 @@ 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\}__ \{\} \{\} +> *\# 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 @@ -286,30 +284,30 @@ 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__" - \} +> 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 \{ - \.\.\. +> __namespace import tepam::\*__ +> +> __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ \{display\_message\} \{ +>    \-args \{ +>       \.\.\. ## Procedure Attributes The first group of attributes affect the behavior of the declared procedure: @@ -365,16 +363,16 @@ 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\}__ - \} \{ - \} +> 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\. @@ -435,33 +433,35 @@ ## 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"\} - \}__ - \} \{ - \} +> 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 __\{ - \{ \.\.\.\} - \{ \.\.\.\} - \.\.\. - \}__ - \} +> tepam::procedure \{ +>    \-args __\{__ +>       __\{ \.\.\.\}__ +>       __\{ \.\.\.\}__ +>       __\.\.\.__ +>    __\}__ +> +> \} The argument names and attributes have to be used in the following way: - Argument name \(*>*\) @@ -475,39 +475,37 @@ 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* +> 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* +> 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 @@ -521,23 +519,23 @@ * *"\-"* 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\]" - \} +> 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\. @@ -549,24 +547,24 @@ 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\] - \} +> 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: @@ -653,16 +651,16 @@ 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\}__\} - \} \{ - \} +> 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\. @@ -684,27 +682,27 @@ 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 \{\- \\ - \- - \.\.\. - \} + -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\}\} \}\}__\} - \} - \} \{ - \} +> 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 @@ -711,14 +709,14 @@ 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 \{\- \\ - \- - \.\.\. - \} + -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 @@ -731,11 +729,11 @@ 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 + 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\. @@ -747,11 +745,11 @@ argument names\. By setting this variable to __0__ the automatic argument name matching mode is disabled: - set tepam::auto\_argument\_name\_completion 0 + 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\. @@ -765,11 +763,11 @@ 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" + 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*\. @@ -778,11 +776,11 @@ 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 + 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__ @@ -810,20 +808,20 @@ ## 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"\} - \} - \} \{ - \.\.\. - \} +> 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 @@ -830,24 +828,23 @@ 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* +> 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 @@ -871,13 +868,11 @@ 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 - -** +> string is ____ \-strict ** - *boolean* - *integer* @@ -885,13 +880,11 @@ 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 ** - -** +> string is ** ** - *alnum* - *alpha* @@ -921,54 +914,48 @@ 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 +> 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 \. **\} - - \] +> 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 ""\} - - \] + 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 \{\[\\"\*?<>:\]\} - - \] + 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 + 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 + 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 @@ -982,11 +969,11 @@ 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\}\} + proc tepam::Validate(two_char) {v} {expr {[string length $v]==2}} # PROCEDURE CALLS ## Help @@ -995,88 +982,98 @@ 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* +> __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__ +> 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\]" - \} + 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\.* +> __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 @@ -1083,131 +1080,129 @@ 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\]" - \} + 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\.* +> __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'" - \} +> __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 +> 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:'<\-'* +> 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'" - \} +> __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__ +> my\_proc __U1 U2 \-n1 N1 \-n2 N2__ +> *\-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'* -*\-> 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\. +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 @@ -1224,85 +1219,87 @@ 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 +> 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 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:''* +> 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\}* +> 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) 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 @@ -83,13 +83,13 @@ 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\! + % 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\. @@ -128,11 +128,11 @@ 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 \.\.\.*? + > *expanderName* option ?*arg arg \.\.\.*? *Option* and the *arg*s determine the exact behavior of the command\. The following commands are possible for expander objects: @@ -277,11 +277,11 @@ ## Basics To begin, create an expander object: % package require textutil::expander - 1\.2 + 1.2 % ::textutil::expander myexp ::myexp % The created __::myexp__ object can be used to expand text strings containing @@ -289,48 +289,48 @@ 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\! + % 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"\} + % 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\! + % ::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\]\} + % 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 @@ -346,18 +346,18 @@ 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\} + % ::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\} \{< >\} + % ::myexp setbrackets "\\[" "\\]" + % ::myexp expand {This is boldface} {< >} This is boldface % ## Customized Macro Expansion @@ -369,30 +369,30 @@ 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\} + 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"\] + 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\] + 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 @@ -401,20 +401,20 @@ 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 \{\} \{ + proc footnote {} { ::myexp cpush footnote - \} - - proc /footnote \{\} \{ - set footnoteText \[::myexp cpop footnote\] - - \# Save the footnote text, and return an appropriate footnote - \# number and link\. - \} + } + + 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\. @@ -424,23 +424,23 @@ 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\} \{ + 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\. - \} + # 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__\. ADDED embedded/md/tcllib/files/modules/textutil/patch.md Index: embedded/md/tcllib/files/modules/textutil/patch.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/textutil/patch.md @@ -0,0 +1,108 @@ + +[//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 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 @@ -468,21 +468,21 @@ 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 - \-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- + ----------- ----------- + 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 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 @@ -102,16 +102,16 @@ __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\] + 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 \{\} + 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\. @@ -124,22 +124,22 @@ 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\]" + 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"\}\} + ::tiff::addEntry photo.tif {{010e 2 "an example photo"} {013b 2 "Aaron F"}} The data types are defined as follows * __1__ 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 @@ -78,21 +78,21 @@ 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 \{ + 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 + } + 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 @@ -105,16 +105,16 @@ purpose\. The difference is that it cannot be used in the class definition itself\. Example: - % oo::class create Foo \{ - method bar \{z\} \{ + % oo::class create Foo { + method bar {z} { classvariable x y - return \[incr x $z\],\[incr y\] - \} - \} + return [incr x $z],[incr y] + } + } ::Foo % Foo create a ::a % Foo create b ::b @@ -122,11 +122,11 @@ 2,1 % a bar 3 5,2 % b bar 7 12,3 - % b bar \-1 + % b bar -1 11,4 % a bar 0 11,5 - __link__ *method*\.\.\. @@ -141,18 +141,18 @@ 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\. + # 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 {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 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*\.\.\.? @@ -163,18 +163,18 @@ Syntax and results are like for __oo::class__\. Example: - % oo::class create example \{ + % oo::class create example { self mixin singleton - method foo \{\} \{self\} - \} + method foo {} {self} + } ::example - % \[example new\] foo + % [example new] foo ::oo::Obj22 - % \[example new\] foo + % [example new] foo ::oo::Obj22 # AUTHORS Donal Fellows, Andreas Kupries 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 @@ -79,27 +79,27 @@ 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 \{ + # 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__ @@ -160,16 +160,16 @@ - 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%\]\} + 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* @@ -251,31 +251,31 @@ 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\} \{ + tool::class myclass { + constructor script { + my Eval_Script $script + } + method node {nodename info} { my variable node dict set node $nodename $info - \} - method get \{args\} \{ + } + 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\} \{ + 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: + 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__\. 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 @@ -222,17 +222,17 @@ 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 + # Load and initialize tls package require tls - tls::init \-cafile /path/to/ca/cert \-keyfile \.\.\. + tls::init -cafile /path/to/ca/cert -keyfile ... - \# Create a connector with secure socket setup, - transfer::connect C \-socketcmd tls::socket \.\.\. - \.\.\. + # 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\. @@ -251,13 +251,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... 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 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 @@ -268,17 +268,17 @@ 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 + # Load and initialize tls package require tls - tls::init \-cafile /path/to/ca/cert \-keyfile \.\.\. + tls::init -cafile /path/to/ca/cert -keyfile ... - \# Create a connector with secure socket setup, - transfer::receiver R \-socketcmd tls::socket \.\.\. - \.\.\. + # 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\. @@ -297,13 +297,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... 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 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 @@ -78,11 +78,11 @@ 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\.\.\.\} + {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 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 @@ -281,17 +281,17 @@ 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 + # Load and initialize tls package require tls - tls::init \-cafile /path/to/ca/cert \-keyfile \.\.\. + tls::init -cafile /path/to/ca/cert -keyfile ... - \# Create a connector with secure socket setup, - transfer::transmitter T \-socketcmd tls::socket \.\.\. - \.\.\. + # 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\. @@ -310,13 +310,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... 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 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,11 +1,11 @@ [//000000001]: # (treeql \- Tree Query Language) [//000000002]: # (Generated from file 'treeql\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Colin McCormack -Copyright © 2004 Andreas Kupries ) -[//000000004]: # (treeql\(n\) 1\.3\.1 tcllib "Tree Query Language") +[//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 | EXAMPLES - __throw__ \{MYERROR CODE\} "My error message" +> __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 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 @@ -108,27 +108,27 @@ # 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 - \} +> 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" - \} +> __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 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 @@ -52,24 +52,24 @@ Using udpcluster\. For every service you wish to publish invoke: - cluster::publish echo@\[cluster::macid\] \{port 10000 protocol echo\} + 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 \{ + set results [cluster::search PATTERN] + # And inside that result... + echo@LOCALMACID { port 10000 protocol echo - \} + } To unpublish a service: - cluster::unpublish echo@\[cluster::macid\] + 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\. 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 @@ -93,18 +93,18 @@ 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 "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 + 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 @@ -111,11 +111,11 @@ 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 + 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* @@ -128,11 +128,11 @@ kind of new universal property\. % ::units::new furlong "220 yards" % ::units::new fortnight "14 days" % ::units::convert 100m/s furlongs/fortnight - 601288\.475303 + 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 @@ -165,34 +165,34 @@ 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 + ------------------------------------------------------------ + 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\. +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\. - \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + Quantity Unit Name Abbr. + --------------------------------------------- Length meter m Mass kilogram kg Time second s Current ampere A Temperature kelvin K @@ -199,31 +199,31 @@ Amount mole mol Luminous Intensity candela cd ## SI Derived Units with Special Names - Quantity Unit Name Abbr\. Units Base Units - \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 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 + 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 @@ -237,16 +237,16 @@ 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*\. +defined in Table 5 of *Special Publication* *330* \. ## SI Prefixes - Prefix Name Abbr\. Factor - \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + Prefix Name Abbr. Factor + --------------------------------------- yotta Y 1e24 zetta Z 1e21 exa E 1e18 peta P 1e15 tera T 1e12 @@ -255,20 +255,20 @@ 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 + 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\. @@ -281,45 +281,45 @@ 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 + 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 @@ -339,22 +339,22 @@ 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\. +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 +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, 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 @@ -458,24 +458,24 @@ 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$\_\.\+\!\*'\(,\)?:@&=\-\] + [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 + % uri::join path /C:/Other%20Files/startup.txt scheme file + + file:///C:/Other%20Files/startup.txt - file:///C:/Other%20Files/startup\.txt + % uri::split file:///C:/Other%20Files/startup.txt - % uri::split file:///C:/Other%20Files/startup\.txt - - path /C:/Other%20Files/startup\.txt scheme file + 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\. 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 @@ -65,11 +65,11 @@ Compares two uuids and returns true if both arguments are the same uuid\. # EXAMPLES % uuid::uuid generate - b12dc22c\-5c36\-41d2\-57da\-e29d0ef5839c + 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)\) 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 @@ -58,12 +58,12 @@ 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\)\. + 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\. 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 @@ -58,12 +58,12 @@ 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\)\. + 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\. 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 @@ -59,12 +59,12 @@ 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\)\. + 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\. 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 @@ -58,12 +58,12 @@ 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\)\. + 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\. 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 @@ -57,12 +57,12 @@ 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\)\. + 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\. 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 @@ -57,12 +57,12 @@ 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\)\. + 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\. 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 @@ -58,12 +58,12 @@ 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\)\. + 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\. 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 @@ -58,12 +58,12 @@ 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\)\. + 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\. 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 @@ -58,12 +58,12 @@ 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\)\. + 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\. 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 @@ -58,12 +58,12 @@ 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\)\. + 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\. 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 @@ -58,12 +58,12 @@ 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\)\. + 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\. 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 @@ -58,12 +58,12 @@ 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\)\. + 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\. 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,10 +1,10 @@ [//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 tcllib "Reflected/virtual channel support") +[//000000004]: # (tcl::chan::cat\(n\) 1\.0\.3 tcllib "Reflected/virtual channel support")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.5 package require TclOO package require tcl::chan::core ?1? -package require tcl::chan::cat ?1? +package require tcl::chan::cat ?1\.0\.3? [__::tcl::chan::cat__ *chan*\.\.\.](#1) # DESCRIPTION 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,10 +1,10 @@ [//000000001]: # (tcl::chan::halfpipe \- Reflected/virtual channel support) [//000000002]: # (Generated from file 'halfpipe\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::chan::halfpipe\(n\) 1 tcllib "Reflected/virtual channel support") +[//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 | 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? +package require tcl::chan::halfpipe ?1\.0\.1? [__::tcl::chan::halfpipe__ ?__\-option__ *value*\.\.\.?](#1) [*objectCmd* __put__ *bytes*](#2) # DESCRIPTION @@ -124,6 +123,6 @@ Channels # COPYRIGHT -Copyright © 2009 Andreas Kupries +Copyright © 2009, 2019 Andreas Kupries 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 @@ -425,32 +425,32 @@ 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\* \{ + proc handler { sock type msg } { + switch -glob -nocase -- $type { + co* { puts "Connected on $sock" - \} - te\* \{ + } + 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\] + } + 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 @@ -471,13 +471,13 @@ 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 + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - \.\.\. your own application code \.\.\. + ... 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 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,11 +1,11 @@ [//000000001]: # (huddle \- HUDDLE) [//000000002]: # (Generated from file 'huddle\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008\-2011 KATO Kanryu -Copyright © 2015 Miguel Martínez López ) -[//000000004]: # (huddle\(n\) 0\.3 tcllib "HUDDLE") +[//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 | - \{HUDDLE \{huddle\-node\}\} - huddle\-node: > - \{tag content\} + 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 + 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\) + - JSON + - YAML(generally, but cannot discribe YAML-tags) limitation: - \- cannot discribe aliases from a node to other node\. + - 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\. @@ -169,26 +169,26 @@ - __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\}\}\} + % 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 {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\}\}\} + % 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 \.\.\.*? @@ -195,18 +195,18 @@ - __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\}\}\} + % 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 {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 {L {{s i} {s j} {s k} {s l} {s g} {s h} {s i}}} - __huddle keys__ *object* The same as __dict keys__\. @@ -241,15 +241,15 @@ * ____null____ the node is a null\. - % huddle type \{HUDDLE \{s str\}\} + % huddle type {HUDDLE {s str}} string - % huddle type \{HUDDLE \{L \{\{s a\} \{s b\} \{s c\}\}\}\} + % huddle type {HUDDLE {L {{s a} {s b} {s c}}}} list - % huddle type \{HUDDLE \{D \{aa \{s b\} cc \{s d\}\}\}\} cc + % 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\. @@ -260,31 +260,31 @@ * ____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\}\}\}\} - \[ - \[ + # 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, + "\\k", + [ + 1.0, true, - "\\/g", + "\/g", "h" - \], - \["g"\] - \], + ], + ["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"\}\} + ] + # 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: @@ -315,14 +315,14 @@ * 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 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\. @@ -335,18 +335,18 @@ 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 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\. @@ -353,11 +353,11 @@ Create a huddle object from *src* with specified *tag*\. % huddle wrap "" str HUDDLE str % huddle wrap s str - HUDDLE \{s str\} + HUDDLE {s str} - __huddle call__ *tag* *command* *args* for type\-callbacks\. @@ -429,181 +429,181 @@ 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 \{ + # 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\} + 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\] - \} + } + # 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 + } + 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\} - \} + } + 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 \.\.\.?"\}\} + } + 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 \{ + 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 \{ + } + } + 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 \{ + } + } + } + + # 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\} + 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\] - \} - \} - \} + 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 + 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 + # 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 + {bb {a b c d} cc {e f g h}} p {q r} s - \# get a sub node + # get a sub node % huddle get $folding 0 bb - HUDDLE \{D \{a \{s b\} c \{s d\}\}\} + HUDDLE {D {a {s b} c {s d}}} % huddle gets $folding 0 bb a b c d - \# overwrite a node + # 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\}\}\} + 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 + # 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 {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 + {bb {a b c kkk} cc {e f g h}} p {q r} s - \# dump as a JSON stream + # dump as a JSON stream % huddle jsondump $folding - \[ - \{ - "bb": \{ + [ + { + "bb": { "a": "b", "c": "kkk" - \}, - "cc": \[ + }, + "cc": [ "e", "f", "g", "h" - \] - \}, + ] + }, "p", - \[ + [ "q", "r" - \], + ], "s" - \] + ] # LIMITATIONS now printing\. 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 @@ -80,46 +80,46 @@ * ____\-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\} + -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\}\} + -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: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 "" ~\}\} + -m:null {"" {null nil "" ~}} * ____\-validate____ Experiment,old: Output stream contains YAML's\-tag, each node\. - % puts \[::yaml::load \-validate \{\[aaa, bbb\]\}\] + % puts [::yaml::load -validate {[aaa, bbb]}] => - \!\!seq \{\{\!\!str aaa\} \{\!\!str 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 @@ -144,62 +144,62 @@ # 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 + date : 2001-01-23 + bill-to: &id001 given : Chris family : Dumars address: - lines: | - 458 Walkman Dr\. - Suite \#292 + lines: | + 458 Walkman Dr. + Suite #292 city : Royal Oak state : MI postal : 48046 - ship\-to: \*id001 + ship-to: *id001 product: - \- sku : BL394D + - sku : BL394D quantity : 4 description : Basketball - price : 450\.00 - \- sku : BL4438H + price : 450.00 + - sku : BL4438H quantity : 1 description : Super Hoop - price : 2392\.00 - tax : 251\.42 - total: 4443\.52 + price : 2392.00 + tax : 251.42 + total: 4443.52 comments: - Late afternoon is best\. + Late afternoon is best. Backup contact is Nancy - Billsmer @ 338\-4338\. - \} + 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\.\} + 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} + } => - \{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\. 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,10 +1,10 @@ [//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 tcllib "Zip archive creation") +[//000000004]: # (zipfile::mkzip\(n\) 1\.2\.1 tcllib "Zip archive creation")
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | SYNOPSIS package require Tcl 8\.6 -package require zipfile::mkzip ?1\.2? +package require zipfile::mkzip ?1\.2\.1? [__::zipfile::mkzip::mkzip__ *zipfile* ?__\-zipkit__? ?__\-runtime__ *prefix*? ?__\-comment__ *string*? ?__\-directory__ *rootpath*? ?__\-exclude__ *exclude*? ?__\-\-__? ?*path*\.\.\.?](#1) # DESCRIPTION @@ -60,11 +60,11 @@ 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 + > __::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\. @@ -71,11 +71,11 @@ 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 + mkzip mystuff.exe -directory mystuff.vfs -runtime unzipsfx.exe The "unzipsfx\.exe" is the Info\-Zip self\-extracting stub\. Accepted options: @@ -103,11 +103,11 @@ 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/\* \*~ "\.\#\*" "\*/\.\#\*" + 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\. Index: embedded/md/tcllib/toc.md ================================================================== --- embedded/md/tcllib/toc.md +++ embedded/md/tcllib/toc.md @@ -41,10 +41,12 @@ - [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 ISO 8601 dates/times - [cmdline](tcllib/files/modules/cmdline/cmdline\.md) Procedures to process command lines and options\. @@ -234,10 +236,12 @@ - [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 @@ -282,10 +286,12 @@ - [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 @@ -370,10 +376,12 @@ - [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::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 @@ -618,10 +626,12 @@ - [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 @@ -707,18 +717,30 @@ - [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 + - [tclrep/machineparameters](tcllib/files/modules/math/machineparameters\.md) Compute double precision machine parameters\. - [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 @@ -755,10 +777,12 @@ - [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\. @@ -773,12 +797,10 @@ - [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/httpd/httpd\.md) A TclOO and coroutine based web server - - [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 Index: embedded/md/toc.md ================================================================== --- embedded/md/toc.md +++ embedded/md/toc.md @@ -401,10 +401,12 @@ + [math::PCA](tcllib/files/modules/math/pca\.md) Package for Principal Component Analysis + [math::polynomials](tcllib/files/modules/math/polynomials\.md) Polynomial functions + + [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 @@ -433,11 +435,15 @@ + [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 @@ -493,12 +499,10 @@ + [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 - + [tool](tcllib/files/modules/httpd/httpd\.md) A TclOO and coroutine based web server - + [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 @@ -616,10 +620,12 @@ + [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\) @@ -793,10 +799,12 @@ + [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\. @@ -828,17 +836,17 @@ + [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 - + [imap4](tcllib/files/modules/imap4/imap4\.md) imap client\-side tcl implementation of imap protocol - + [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 @@ -854,10 +862,12 @@ + [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 + [tclrep/machineparameters](tcllib/files/modules/math/machineparameters\.md) Compute double precision machine parameters\. + [uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md) Request merging and deferal to idle time @@ -1001,10 +1011,14 @@ + [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 ISO 8601 dates/times @@ -1234,10 +1248,12 @@ - [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]() @@ -1321,11 +1337,11 @@ - [autoproxy](tcllib/files/modules/http/autoproxy\.md) Automatic HTTP proxy usage and authentication + [httpd]() - - [tool](tcllib/files/modules/httpd/httpd\.md) A TclOO and coroutine based web server + - [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 @@ -1446,10 +1462,12 @@ - [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::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 @@ -1766,10 +1784,12 @@ - [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 @@ -1836,10 +1856,12 @@ - [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 Index: embedded/md/toc0.md ================================================================== --- embedded/md/toc0.md +++ embedded/md/toc0.md @@ -401,10 +401,12 @@ + [math::PCA](tcllib/files/modules/math/pca\.md) Package for Principal Component Analysis + [math::polynomials](tcllib/files/modules/math/polynomials\.md) Polynomial functions + + [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 @@ -433,11 +435,15 @@ + [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 @@ -493,12 +499,10 @@ + [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 - + [tool](tcllib/files/modules/httpd/httpd\.md) A TclOO and coroutine based web server - + [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 @@ -616,10 +620,12 @@ + [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\) @@ -793,10 +799,12 @@ + [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\. @@ -828,17 +836,17 @@ + [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 - + [imap4](tcllib/files/modules/imap4/imap4\.md) imap client\-side tcl implementation of imap protocol - + [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 @@ -854,10 +862,12 @@ + [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 + [tclrep/machineparameters](tcllib/files/modules/math/machineparameters\.md) Compute double precision machine parameters\. + [uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md) Request merging and deferal to idle time Index: embedded/md/toc1.md ================================================================== --- embedded/md/toc1.md +++ embedded/md/toc1.md @@ -67,10 +67,14 @@ * [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 ISO 8601 dates/times @@ -300,10 +304,12 @@ + [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]() @@ -387,11 +393,11 @@ + [autoproxy](tcllib/files/modules/http/autoproxy\.md) Automatic HTTP proxy usage and authentication * [httpd]() - + [tool](tcllib/files/modules/httpd/httpd\.md) A TclOO and coroutine based web server + + [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 @@ -512,10 +518,12 @@ + [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::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 @@ -832,10 +840,12 @@ + [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 @@ -902,10 +912,12 @@ + [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 Index: examples/httpd/htdocs/index.md ================================================================== --- examples/httpd/htdocs/index.md +++ examples/httpd/htdocs/index.md @@ -2,10 +2,11 @@ * [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: Index: examples/httpd/httpd.tcl ================================================================== --- examples/httpd/httpd.tcl +++ examples/httpd/httpd.tcl @@ -25,35 +25,17 @@ return $::fossil_exe } return [exec ${::fossil_exe} {*}$args] } -tool::define httpd::content.fossil_root { - - method content {} { - 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 {
} - } -} - - -tool::define httpd::content.fossil_node_proxy { +clay::define httpd::content.fossil_node_proxy { superclass httpd::content.proxy method FileName {} { - set uri [my http_info get REQUEST_URI] - set prefix [my http_info get prefix] + 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 @@ -69,12 +51,12 @@ } return [list $module $::fossil_process($module)] } method proxy_path {} { - set uri [string trimleft [my http_info get REQUEST_URI] /] - set prefix [my http_info get prefix] + 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 } @@ -83,25 +65,25 @@ # 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 http_info get HTTP_HOST][my http_info get prefix]/$module + 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+] } } } -tool::define httpd::content.fossil_node_scgi { +clay::define httpd::content.fossil_node_scgi { superclass httpd::content.scgi method scgi_info {} { - set uri [my http_info get REQUEST_URI] - set prefix [my http_info get prefix] + set uri [my request get REQUEST_URI] + set prefix [my clay get prefix] set module [lindex [split $uri /] 2] file mkdir ~/tmp if {![info exists ::fossil_process($module)]} { package require processman package require nettool @@ -131,92 +113,84 @@ } return [list localhost $port $SCRIPT_NAME] } } -tool::class create ::docserver::server { - superclass ::httpd::server - - method log args { - #puts [list {*}$args] - } - -} - -tool::define ::docserver::dynamic { - - method content {} { - my puts "IRM Dispatch Server" - my puts "" - foreach {f v} [my request dump] { - my puts "" - } - my puts "" - foreach {f v} [my http_info dump] { - my puts "" - } - my puts "" - my puts
$f$v
$f$v
File Size[my http_info get CONTENT_LENGTH]
- my puts - } - -} - -tool::define ::docserver::upload { - superclass ::docserver::dynamic - - method content {} { - my puts "IRM Dispatch Server" - my puts "" - set FORMDAT [my FormData] - foreach {f v} [my FormData] { - my puts "" - } - my puts "" - foreach {f v} [my http_info 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 http_info get CONTENT_LENGTH]
- my puts - } -} - -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 - } -} -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] +::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]} { + dict set serveropts $f $v + } +} +if {[dict exists $serveropts fossil]} { + set ::fossil_exe [dict get $serveropts fossil] } ::docserver::server create appmain doc_root $DEMOROOT {*}$argv appmain plugin basic_url ::httpd::plugin.dict_dispatch -appmain uri add /tcllib* [list mixin httpd::content.file path [file join $tcllibroot embedded www]] -appmain uri add /fossil [list mixin httpd::content.fossil_root {*}$fossilopts] -appmain uri add /fossil/* [list mixin httpd::content.fossil_node_proxy {*}$fossilopts] -appmain uri add /upload [list mixin ::docserver::upload] -appmain uri add /dynamic [list mixin ::docserver::dynamic] -appmain uri add /listen [list mixin ::docserver::listen] -appmain uri add /send [list mixin ::docserver::send] +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]] -tool::main +cron::main ADDED idoc/man/files/devdoc/tcl_community_communication.n Index: idoc/man/files/devdoc/tcl_community_communication.n ================================================================== --- /dev/null +++ idoc/man/files/devdoc/tcl_community_communication.n @@ -0,0 +1,434 @@ +'\" +'\" 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 ADDED idoc/man/files/devdoc/tcllib_devguide.n Index: idoc/man/files/devdoc/tcllib_devguide.n ================================================================== --- /dev/null +++ idoc/man/files/devdoc/tcllib_devguide.n @@ -0,0 +1,1307 @@ +'\" +'\" 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\&. ADDED idoc/man/files/devdoc/tcllib_installer.n Index: idoc/man/files/devdoc/tcllib_installer.n ================================================================== --- /dev/null +++ idoc/man/files/devdoc/tcllib_installer.n @@ -0,0 +1,596 @@ +'\" +'\" 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 installed by +default\&. +.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 # This builds the shared library holding + # the accelerators + make install + +.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 ADDED idoc/man/files/devdoc/tcllib_license.n Index: idoc/man/files/devdoc/tcllib_license.n ================================================================== --- /dev/null +++ idoc/man/files/devdoc/tcllib_license.n @@ -0,0 +1,321 @@ +'\" +'\" 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\&. ADDED idoc/man/files/devdoc/tcllib_releasemgr.n Index: idoc/man/files/devdoc/tcllib_releasemgr.n ================================================================== --- /dev/null +++ idoc/man/files/devdoc/tcllib_releasemgr.n @@ -0,0 +1,359 @@ +'\" +'\" 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 ADDED idoc/man/files/devdoc/tcllib_sources.n Index: idoc/man/files/devdoc/tcllib_sources.n ================================================================== --- /dev/null +++ idoc/man/files/devdoc/tcllib_sources.n @@ -0,0 +1,332 @@ +'\" +'\" 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\&. ADDED idoc/man/files/modules/clay/clay.n Index: idoc/man/files/modules/clay/clay.n ================================================================== --- /dev/null +++ idoc/man/files/modules/clay/clay.n @@ -0,0 +1,1071 @@ +'\" +'\" 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/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 tcllib "debug narrative" +.TH "debug::heartbeat" n 1\&.0\&.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?\fR +package require \fBdebug::heartbeat ?1\&.0\&.1?\fR .sp package require \fBdebug ?1?\fR .sp \fBdebug\fR \fBheartbeat\fR ?\fIdelta\fR? .sp Index: idoc/man/files/modules/dicttool/dicttool.n ================================================================== --- idoc/man/files/modules/dicttool/dicttool.n +++ idoc/man/files/modules/dicttool/dicttool.n @@ -274,10 +274,12 @@ .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 @@ -299,11 +301,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 add a delete all instances of each element in \fIargs\fR from \fIvarname\fR\&. +This command will 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 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\&.4\&.0 tcllib "Domain Name Service" +.TH "dns" n 1\&.4\&.1 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\&.4\&.0?\fR +package require \fBdns ?1\&.4\&.1?\fR .sp \fB::dns::resolve\fR \fIquery\fR ?\fIoptions\fR? .sp \fB::dns::configure\fR ?\fIoptions\fR? .sp 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 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 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 '\" -.TH "doctools" n 1\&.5\&.1 tcllib "Documentation tools" +.TH "doctools" n 1\&.5\&.6 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\&.1?\fR +package require \fBdoctools ?1\&.5\&.6?\fR .sp \fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR\&.\&.\&.? .sp \fB::doctools::help\fR .sp 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 \&.\&./doctools2base/include/feedback\&.inc] +[include \&.\&./common-text/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 @@ -391,11 +391,11 @@ [manpage_begin NAME SECTION VERSION] [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE] [require PACKAGE VERSION][require PACKAGE][description] [vset CATEGORY doctools] -[include \&.\&./doctools2base/include/feedback\&.inc] +[include \&.\&./common-text/feedback\&.inc] [manpage_end] .CE has the same meaning as the example before\&. .PP 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 Andreas Kupries +'\" Copyright (c) 2009-2019 Andreas Kupries '\" -.TH "doctools::idx::export::docidx" n 0\&.1 tcllib "Documentation tools" +.TH "doctools::idx::export::docidx" n 0\&.2\&.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\&.1?\fR +package require \fBdoctools::idx::export::docidx ?0\&.2\&.1?\fR .sp \fBexport\fR \fIserial\fR \fIconfiguration\fR .sp .BE .SH DESCRIPTION @@ -466,8 +466,8 @@ docidx, doctools, export, index, serialization .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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-2018 Andreas Kupries +'\" Copyright (c) 2009-2019 Andreas Kupries '\" -.TH "doctools::idx::export" n 0\&.2 tcllib "Documentation tools" +.TH "doctools::idx::export" n 0\&.2\&.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?\fR +package require \fBdoctools::idx::export ?0\&.2\&.1?\fR .sp package require \fBTcl 8\&.4\fR .sp -package require \fBdoctools::config \fR +package require \fBstruct::map \fR .sp package require \fBdoctools::idx::structure \fR .sp package require \fBsnit \fR .sp @@ -672,8 +672,8 @@ 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-2018 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 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. .\" @@ -551,8 +551,8 @@ HTML, doctools, export, index, serialization .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 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. .\" @@ -483,8 +483,8 @@ JSON, doctools, export, index, serialization .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 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. .\" @@ -434,8 +434,8 @@ doctools, export, index, nroff, serialization .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 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. .\" @@ -418,8 +418,8 @@ doctools, export, index, plain text, serialization .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 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. .\" @@ -431,8 +431,8 @@ doctools, export, index, serialization, wiki .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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-2018 Andreas Kupries +'\" Copyright (c) 2009-2019 Andreas Kupries '\" -.TH "doctools::idx::import" n 0\&.2 tcllib "Documentation tools" +.TH "doctools::idx::import" n 0\&.2\&.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?\fR +package require \fBdoctools::idx::import ?0\&.2\&.1?\fR .sp package require \fBTcl 8\&.4\fR .sp -package require \fBdoctools::config \fR +package require \fBstruct::map \fR .sp package require \fBdoctools::idx::structure \fR .sp package require \fBsnit \fR .sp @@ -751,8 +751,8 @@ conversion, docidx, documentation, import, index, json, keyword index, manpage, markup, parsing, plugin, reference, url .SH CATEGORY Documentation tools .SH COPYRIGHT .nf -Copyright (c) 2009-2018 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 Andreas Kupries '\" -.TH "doctools::idx::import::json" n 0\&.1 tcllib "Documentation tools" +.TH "doctools::idx::import::json" n 0\&.2\&.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\&.4\fR +package require \fBTcl 8\&.5\fR .sp -package require \fBdoctools::idx::import::json ?0\&.1?\fR +package require \fBdoctools::idx::import::json ?0\&.2\&.1?\fR .sp package require \fBdoctools::idx::structure \fR .sp package require \fBjson \fR .sp @@ -460,8 +460,8 @@ JSON, deserialization, doctools, import, index .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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 | | | +---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+ | | | | | | | | | -doctools::config = | | | = doctools::include doctools::config doctools::paths +struct::map = | | | = doctools::include struct::map fileutil::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 | | +-------+---------------+ 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 Andreas Kupries +'\" Copyright (c) 2009-2019 Andreas Kupries '\" -.TH "doctools::idx::import::docidx" n 0\&.1 tcllib "Documentation tools" +.TH "doctools::idx::import::docidx" n 0\&.2\&.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\&.4\fR +package require \fBTcl 8\&.5\fR .sp -package require \fBdoctools::idx::import::docidx ?0\&.1?\fR +package require \fBdoctools::idx::import::docidx ?0\&.2\&.1?\fR .sp package require \fBdoctools::idx::parse \fR .sp package require \fBdoctools::idx::structure \fR .sp @@ -442,8 +442,8 @@ deserialization, docidx, doctools, import, index .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 Andreas Kupries '\" -.TH "doctools::toc::export::doctoc" n 0\&.1 tcllib "Documentation tools" +.TH "doctools::toc::export::doctoc" n 0\&.2\&.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\&.1?\fR +package require \fBdoctools::toc::export::doctoc ?0\&.2\&.1?\fR .sp \fBexport\fR \fIserial\fR \fIconfiguration\fR .sp .BE .SH DESCRIPTION @@ -493,8 +493,8 @@ doctoc, doctools, export, serialization, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 Andreas Kupries '\" -.TH "doctools::toc::import::doctoc" n 0\&.1 tcllib "Documentation tools" +.TH "doctools::toc::import::doctoc" n 0\&.2\&.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\&.4\fR +package require \fBTcl 8\&.5\fR .sp -package require \fBdoctools::toc::import::doctoc ?0\&.1?\fR +package require \fBdoctools::toc::import::doctoc ?0\&.2\&.1?\fR .sp package require \fBdoctools::toc::parse \fR .sp package require \fBdoctools::toc::structure \fR .sp @@ -470,8 +470,8 @@ deserialization, doctoc, doctools, import, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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-2018 Andreas Kupries +'\" Copyright (c) 2009-2019 Andreas Kupries '\" -.TH "doctools::toc::export" n 0\&.2 tcllib "Documentation tools" +.TH "doctools::toc::export" n 0\&.2\&.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?\fR +package require \fBdoctools::toc::export ?0\&.2\&.1?\fR .sp package require \fBTcl 8\&.4\fR .sp -package require \fBdoctools::config \fR +package require \fBstruct::map \fR .sp package require \fBdoctools::toc::structure \fR .sp package require \fBsnit \fR .sp @@ -689,8 +689,8 @@ 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-2018 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 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. .\" @@ -543,8 +543,8 @@ HTML, doctools, export, serialization, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 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. .\" @@ -531,8 +531,8 @@ JSON, doctools, export, serialization, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 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. .\" @@ -462,8 +462,8 @@ doctools, export, nroff, serialization, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 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. .\" @@ -445,8 +445,8 @@ doctools, export, plain text, serialization, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 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. .\" @@ -451,8 +451,8 @@ doctools, export, serialization, table of contents, toc, wiki .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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-2018 Andreas Kupries +'\" Copyright (c) 2009-2019 Andreas Kupries '\" -.TH "doctools::toc::import" n 0\&.2 tcllib "Documentation tools" +.TH "doctools::toc::import" n 0\&.2\&.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?\fR +package require \fBdoctools::toc::import ?0\&.2\&.1?\fR .sp package require \fBTcl 8\&.4\fR .sp -package require \fBdoctools::config \fR +package require \fBstruct::map \fR .sp package require \fBdoctools::toc::structure \fR .sp package require \fBsnit \fR .sp @@ -770,8 +770,8 @@ 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-2018 Andreas Kupries +Copyright (c) 2009-2019 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 Andreas Kupries +'\" Copyright (c) 2009-2019 Andreas Kupries '\" -.TH "doctools::toc::import::json" n 0\&.1 tcllib "Documentation tools" +.TH "doctools::toc::import::json" n 0\&.2\&.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\&.4\fR +package require \fBTcl 8\&.5\fR .sp -package require \fBdoctools::toc::import::json ?0\&.1?\fR +package require \fBdoctools::toc::import::json ?0\&.2\&.1?\fR .sp package require \fBdoctools::toc::structure \fR .sp package require \fBjson \fR .sp @@ -508,8 +508,8 @@ JSON, deserialization, doctools, import, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009-2019 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 | | | +---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+ | | | | | | | | | -doctools::config = | | | = doctools::include doctools::config doctools::paths +struct:map = | | | = doctools::include struct::map fileutil::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 | | +-------+---------------+ 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 ADDED idoc/man/files/modules/fileutil/paths.n Index: idoc/man/files/modules/fileutil/paths.n ================================================================== --- /dev/null +++ idoc/man/files/modules/fileutil/paths.n @@ -0,0 +1,350 @@ +'\" +'\" 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/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 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 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\&.4\&.4 tcllib "HTML Generation" +.TH "html" n 1\&.5 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\&.4\&.4?\fR +package require \fBhtml ?1\&.5?\fR .sp \fB::html::author\fR \fIauthor\fR .sp \fB::html::bodyTag\fR \fIargs\fR .sp @@ -343,10 +343,16 @@ .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 @@ -381,11 +387,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? +\fB::html::submit\fR \fIlabel\fR ?\fIname\fR? ?\fItitle\fR? .sp \fB::html::tableFromArray\fR \fIarrname\fR ?\fIparam\fR? ?\fIpat\fR? .sp \fB::html::tableFromList\fR \fIquerylist\fR ?\fIparam\fR? .sp @@ -398,10 +404,12 @@ \fB::html::varEmpty\fR \fIname\fR .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\&. @@ -587,13 +595,35 @@ .TP \fB::html::mailto\fR \fIemail\fR ?\fIsubject\fR? Generate a hypertext link to a mailto: URL\&. .TP \fB::html::meta\fR \fIargs\fR -\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 +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 \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 @@ -707,12 +737,15 @@ 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? -Generate an \fIinput\fR tag of type \fIsubmit\fR\&. \fIname\fR defaults to "submit"\&. +\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\&. .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 @@ -780,10 +813,17 @@ .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 Index: idoc/man/files/modules/httpd/httpd.n ================================================================== --- idoc/man/files/modules/httpd/httpd.n +++ idoc/man/files/modules/httpd/httpd.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'httpd\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2018 Sean Woods '\" -.TH "tool" n 4\&.1\&.1 tcllib "Tcl Web Server" +.TH "httpd" n 4\&.3\&.4 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. @@ -270,25 +270,17 @@ .de MT .QW "" .. .BS .SH NAME -tool \- A TclOO and coroutine based web server +httpd \- A TclOO and coroutine based web server .SH SYNOPSIS package require \fBTcl 8\&.6\fR .sp -package require \fBhttpd ?4\&.1\&.1?\fR -.sp -package require \fBsha1 \fR -.sp -package require \fBdicttool \fR -.sp -package require \fBoo::meta \fR -.sp -package require \fBoo::dialect \fR -.sp -package require \fBtool \fR +package require \fBuuid \fR +.sp +package require \fBclay \fR .sp package require \fBcoroutine \fR .sp package require \fBfileutil \fR .sp @@ -302,103 +294,221 @@ .sp package require \fBuri \fR .sp package require \fBMarkdown \fR .sp -constructor ?port ?port?? ?myaddr ?ipaddr?|all? ?server_string ?string?? ?server_name ?string?? -.sp -method \fBadd_uri\fR \fIpattern\fR \fIdict\fR -.sp -method \fBconnect\fR \fIsock\fR \fIip\fR \fIport\fR -.sp -method \fBConnect\fR \fIuuid\fR \fIsock\fR \fIip\fR -.sp -method \fBcounter\fR \fIwhich\fR -.sp -method \fBCheckTimeout\fR -.sp -method \fBdispatch\fR \fIheader_dict\fR -.sp -method \fBlog\fR \fIargs\fR -.sp -method \fBport_listening\fR -.sp -method \fBPrefixNormalize\fR \fIprefix\fR -.sp -method \fBstart\fR -.sp -method \fBstop\fR -.sp -method \fBtemplate\fR \fIpage\fR -.sp -method \fBTemplateSearch\fR \fIpage\fR -.sp -method \fBValidate_Connection\fR \fIsock\fR \fIip\fR -.sp -method \fBENSEMBLE::add\fR \fIfield\fR \fIelement\fR -.sp -method \fBENSEMBLE::dump\fR -.sp -method \fBENSEMBLE::get\fR \fIfield\fR -.sp -method \fBENSEMBLE::reset\fR -.sp -method \fBENSEMBLE::remove\fR \fIfield\fR \fIelement\fR -.sp -method \fBENSEMBLE::replace\fR \fIkeyvaluelist\fR -.sp -method \fBENSEMBLE::reset\fR -.sp -method \fBENSEMBLE::set\fR \fIfield\fR \fIvalue\fR -.sp -method \fBhttp_info::netstring\fR -.sp -method \fBrequest::parse\fR \fIstring\fR -.sp -method \fBreply::output\fR +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 \fBHttpHeaders\fR \fIsock\fR \fI?debug?\fR +method \fBLog_Dispatched\fR .sp method \fBdispatch\fR \fInewsock\fR \fIdatastate\fR .sp -method \fBerror\fR \fIcode\fR \fI?message?\fR \fI?errorInfo?\fR +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 FormData +method \fBlog\fR \fItype\fR ?\fIinfo\fR \fB\fR? .sp -method MimeParse \fImimetext\fR +method \fBCoroName\fR .sp method \fBDoOutput\fR .sp -method PostData \fIlength\fR +method \fBFormData\fR .sp -method \fBputs\fR \fIstring\fR +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 -method \fBTransferComplete\fR \fIargs\fR -.sp -method \fBUrl_Decode\fR \fIstring\fR -.sp -method cgi_info -.sp -option \fBpath\fR -.sp -option \fBprefix\fR -.sp -method proxy_info -.sp -method scgi_info +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 @@ -410,97 +520,79 @@ \fBhttpd::server\fR, and providing that server with one or more URIs to service, and \fBhttpd::reply\fR derived classes to generate them\&. .CS -tool::define ::reply\&.hello { +oo::class create ::reply\&.hello { method content {} { my puts "IRM Dispatch Server" my puts "

Hello World!

" my puts } } -::docserver::server create HTTPD port 8015 myaddr 127\&.0\&.0\&.1 -HTTPD add_uri /* [list mixin reply\&.hello] +::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 "CLASS ::HTTPD::SERVER" -This class is the root object of the webserver\&. It is responsible -for opening the socket and providing the initial connection negotiation\&. -.TP -constructor ?port ?port?? ?myaddr ?ipaddr?|all? ?server_string ?string?? ?server_name ?string?? -Build a new server object\&. ?port? is the port to listen on -.TP -method \fBadd_uri\fR \fIpattern\fR \fIdict\fR -Set the hander for a URI pattern\&. Information given in the \fIdict\fR is stored -in the data structure the \fBdispatch\fR method uses\&. If a field called -\fImixin\fR is given, that class will be mixed into the reply object immediately -after construction\&. -.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 \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\&. -Fields the server are looking for in particular are: -class: A class to use instead of the server's own \fIreply_class\fR -mixin: A class to be mixed into the new object after construction\&. -All other fields are passed along to the \fBhttp_info\fR structure of the -reply object\&. -After the class is created and the mixin is mixed in, the server invokes the -reply objects \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 \fBdispatch\fR \fIheader_dict\fR -Given a key/value list of information, return a data structure describing how -the server should reply\&. -.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 \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 \fBstart\fR -Open the socket listener\&. -.TP -method \fBstop\fR -Shut off the socket listener, and destroy any pending replies\&. -.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 \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 -.SH "CLASS ::HTTPD::REPLY" +.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 @@ -521,82 +613,10 @@ method if an exception is raised\&. .IP [6] Invokes the \fBoutput\fR method for the object .PP .PP -.SH "REPLY METHOD ENSEMBLES" -The \fBhttp::reply\fR class and its derivatives maintain several variables as dictionaries -internally\&. Access to these dictionaries is managed through a dedicated ensemble\&. The -ensemble implements most of the same behaviors as the \fBdict\fR command\&. -Each ensemble implements the following methods above, beyond, or modifying standard dicts: -.TP -method \fBENSEMBLE::add\fR \fIfield\fR \fIelement\fR -Add \fIelement\fR to a list stored in \fIfield\fR, but only if it is not already present om the list\&. -.TP -method \fBENSEMBLE::dump\fR -Return the current contents of the data structure as a key/value list\&. -.TP -method \fBENSEMBLE::get\fR \fIfield\fR -Return the value of the field \fIfield\fR, or an empty string if it does not exist\&. -.TP -method \fBENSEMBLE::reset\fR -Return a key/value list of the default contents for this data structure\&. -.TP -method \fBENSEMBLE::remove\fR \fIfield\fR \fIelement\fR -Remove all instances of \fIelement\fR from the list stored in \fIfield\fR\&. -.TP -method \fBENSEMBLE::replace\fR \fIkeyvaluelist\fR -Replace the internal dict with the contents of \fIkeyvaluelist\fR -.TP -method \fBENSEMBLE::reset\fR -Replace the internal dict with the default state\&. -.TP -method \fBENSEMBLE::set\fR \fIfield\fR \fIvalue\fR -Set the value of \fIfield\fR to \fIvalue\fR\&. -.PP -.SH "REPLY METHOD ENSEMBLE: HTTP_INFO" -Manages HTTP headers passed in by the server\&. -Ensemble Methods: -.TP -method \fBhttp_info::netstring\fR -Return the contents of this data structure as a netstring encoded block\&. -.PP -.SH "REPLY METHOD ENSEMBLE: REQUEST" -Managed data from MIME headers of the request\&. -.TP -method \fBrequest::parse\fR \fIstring\fR -Replace the contents of the data structure with information encoded in a MIME -formatted block of text (\fIstring\fR)\&. -.PP -.SH "REPLY METHOD ENSEMBLE: REPLY" -Manage the headers sent in the reply\&. -.TP -method \fBreply::output\fR -Return the contents of this data structure as a MIME encoded block appropriate -for an HTTP response\&. -.PP -.SH "REPLY METHODS" -.TP -method \fBclose\fR -Terminate the transaction, and close the socket\&. -.TP -method \fBHttpHeaders\fR \fIsock\fR \fI?debug?\fR -Stream MIME headers from the socket \fIsock\fR, stopping at an empty line\&. Returns -the stream as a block of text\&. -.TP -method \fBdispatch\fR \fInewsock\fR \fIdatastate\fR -Take over control of the socket \fInewsock\fR, and store that as the \fIchan\fR variable -for the object\&. This method runs through all of the steps of reading HTTP headers, generating -content, and closing the connection\&. (See class writetup)\&. -.TP -method \fBerror\fR \fIcode\fR \fI?message?\fR \fI?errorInfo?\fR -Generate an error message of the specified \fIcode\fR, and display the \fImessage\fR as the -reason for the exception\&. \fIerrorInfo\fR is passed in from calls, but how or if it should be -displayed is a prerogative of the developer\&. -.TP -method \fBcontent\fR -Generate the content for the reply\&. This method is intended to be replaced by the mixin\&. 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\&. @@ -603,95 +623,164 @@ A typical implementation of \fBcontent\fR look like: .CS -tool::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 http_info get doc_root] - my variable reply_file - set reply_file [file join $doc_root index\&.html] - } -} -tool::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] - } -} -tool::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]] - } -} -tool::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] - } -} + 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 FormData +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 MimeParse \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 \fBDoOutput\fR -Generates the the HTTP reply, and streams that reply back across \fIchan\fR\&. -.TP -method PostData \fIlength\fR +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 \fBputs\fR \fIstring\fR +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 @@ -704,94 +793,324 @@ 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 \fBTransferComplete\fR \fIargs\fR -Intended to be invoked from \fBchan copy\fR as a callback\&. This closes every channel -fed to it on the command line, and then destroys the object\&. +method \fBUuid_Generate\fR +Generate a GUUID\&. Used to ensure every request has a unique ID\&. +The default implementation is: .CS - ### - # 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 - if {$length} { - ### - # Send any POST/PUT/etc content - ### - chan copy $sock $chan -size $SIZE -command [info coroutine] - yield - } - catch {close $sock} - chan flush $chan + return [::clay::uuid generate] .CE .TP -method \fBUrl_Decode\fR \fIstring\fR -De-httpizes a string\&. -.PP -.SH "CLASS ::HTTPD::CONTENT" -The httpd module includes several ready to use implementations of content mixins -for common use cases\&. Options are passed in to the \fBadd_uri\fR method of the server\&. -.SH "CLASS ::HTTPD::CONTENT\&.CGI" -An implementation to relay requests to process which will accept post data -streamed in vie stdin, and sent a reply streamed to stdout\&. -.TP -method cgi_info -Mandatory method to be replaced by the end user\&. If needed, activates the -process to proxy, and then returns a list of three values: -\fIexec\fR - The arguments to send to exec to fire off the responding process, minus the stdin/stdout redirection\&. -.PP -.SH "CLASS ::HTTPD::CONTENT\&.FILE" -An implementation to deliver files from the local file system\&. -.TP -option \fBpath\fR -The root directory on the local file system to be exposed via http\&. -.TP -option \fBprefix\fR -The prefix of the URI portion to ignore when calculating relative file paths\&. -.PP -.SH "CLASS ::HTTPD::CONTENT\&.PROXY" -An implementation to relay requests to another HTTP server, and relay -the results back across the request channel\&. -.TP -method proxy_info -Mandatory method to be replaced by the end user\&. If needed, activates the -process to proxy, and then returns a list of three values: -\fIproxyhost\fR - The hostname where the proxy is located -\fIproxyport\fR - The port to connect to -\fIproxyscript\fR - A pre-amble block of text to send prior to the mirrored request -.PP -.SH "CLASS ::HTTPD::CONTENT\&.SCGI" -An implementation to relay requests to a server listening on a socket -expecting SCGI encoded requests, and relay -the results back across the request channel\&. -.TP -method scgi_info -Mandatory method to be replaced by the end user\&. If needed, activates the -process to proxy, and then returns a list of three values: -\fIscgihost\fR - The hostname where the scgi listener is located -\fIscgiport\fR - The port to connect to -\fIscgiscript\fR - The contents of the \fISCRIPT_NAME\fR header to be sent -.PP -.SH "CLASS ::HTTPD::CONTENT\&.WEBSOCKET" -A placeholder for a future implementation to manage requests that can expect to be -promoted to a Websocket\&. Currently it is an empty class\&. -.SH "SCGI SERVER FUNCTIONS" -The HTTP module also provides an SCGI server implementation, as well as an HTTP -implementation\&. To use the SCGI functions, create an object of the \fBhttp::server\&.scgi\fR -class instead of the \fBhttp::server\fR class\&. -.SH "CLASS ::HTTPD::REPLY\&.SCGI" -An modified \fBhttp::reply\fR implementation that understands how to deal with -netstring encoded headers\&. -.SH "CLASS ::HTTPD::SERVER\&.SCGI" -A modified \fBhttp::server\fR which is tailored to replying to request according to -the SCGI standard instead of the HTTP standard\&. +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\&. 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\&.2?\fR +package require \fBimap4 ?0\&.5\&.3?\fR .sp \fB::imap4::open\fR \fIhostname\fR ?\fIport\fR? .sp \fB::imap4::starttls\fR \fIchan\fR .sp @@ -811,5 +811,7 @@ 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/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 tcllib "Object Oriented logging facility" +.TH "logger::utils" n 1\&.3\&.1 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?\fR +package require \fBlogger::utils ?1\&.3\&.1?\fR .sp \fB::logger::utils::createFormatCmd\fR \fIformatString\fR .sp \fB::logger::utils::createLogProc\fR \fB-procName\fR \fIprocName\fR ?\fIoptions\fR\&.\&.\&.? .sp 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\&.1 tcllib "Markdown to HTML Converter" +.TH "markdown" n 1\&.1\&.1 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,11 +273,11 @@ .SH NAME markdown \- Converts Markdown text to HTML .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBMarkdown 1\&.1\fR +package require \fBMarkdown 1\&.1\&.1\fR .sp package require \fBtextutil ?0\&.8?\fR .sp \fB::Markdown::convert\fR \fImarkdown\fR .sp 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 @@ -307,10 +307,16 @@ .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 @@ -511,10 +517,43 @@ .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 @@ -830,11 +869,11 @@ .TP list \fIvector\fR Translation vector .TP list \fIpolyline\fR -The polyline to be rotated +The polyline to be translated .RE .sp .TP \fB::math::geometry::rotate\fR \fIangle\fR \fIpolyline\fR Rotate a polyline over a given angle (degrees) around the origin @@ -842,11 +881,11 @@ .TP list \fIangle\fR Angle over which to rotate the polyline (degrees) .TP list \fIpolyline\fR -The polyline to be translated +The polyline to be rotated .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 Index: idoc/man/files/modules/math/numtheory.n ================================================================== --- idoc/man/files/modules/math/numtheory.n +++ idoc/man/files/modules/math/numtheory.n @@ -310,10 +310,12 @@ .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\&. @@ -469,27 +471,38 @@ \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 +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 +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 +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\&. ADDED idoc/man/files/modules/math/quasirandom.n Index: idoc/man/files/modules/math/quasirandom.n ================================================================== --- /dev/null +++ idoc/man/files/modules/math/quasirandom.n @@ -0,0 +1,394 @@ +'\" +'\" 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/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\&.3 tcllib "Tcl Math Library" +.TH "math::special" n 0\&.4 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,17 +272,23 @@ .. .BS .SH NAME math::special \- Special mathematical functions .SH SYNOPSIS -package require \fBTcl ?8\&.3?\fR +package require \fBTcl ?8\&.5?\fR .sp -package require \fBmath::special ?0\&.3?\fR +package require \fBmath::special ?0\&.4?\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 @@ -410,10 +416,15 @@ 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 @@ -432,13 +443,11 @@ .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 digamma function (psi) -.IP \(bu -The incomplete gamma and beta functions +The incomplete gamma function .PP .SH PROCEDURES The package defines the following public procedures: .TP \fB::math::special::Beta\fR \fIx\fR \fIy\fR @@ -450,18 +459,57 @@ .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 Index: idoc/man/files/modules/math/statistics.n ================================================================== --- idoc/man/files/modules/math/statistics.n +++ idoc/man/files/modules/math/statistics.n @@ -349,10 +349,14 @@ .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 @@ -383,10 +387,14 @@ .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 @@ -403,18 +411,28 @@ .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 @@ -429,10 +447,16 @@ .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 @@ -439,10 +463,14 @@ .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 @@ -456,19 +484,31 @@ \fB::math::statistics::random-gumbel\fR \fIlocation\fR \fIscale\fR \fInumber\fR .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 @@ -1128,10 +1168,35 @@ .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\&. @@ -1143,11 +1208,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 @@ -1540,10 +1605,44 @@ .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 @@ -1692,10 +1791,61 @@ .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\&. @@ -1744,10 +1894,43 @@ .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 @@ -1893,10 +2076,61 @@ .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 @@ -1953,10 +2187,43 @@ .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 @@ -2099,10 +2366,60 @@ .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 @@ -2167,10 +2484,43 @@ .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: 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 tcllib "Mime" +.TH "mime" n 1\&.6\&.2 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?\fR +package require \fBmime ?1\&.6\&.2?\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 Index: idoc/man/files/modules/mime/smtp.n ================================================================== --- idoc/man/files/modules/mime/smtp.n +++ idoc/man/files/modules/mime/smtp.n @@ -405,19 +405,19 @@ 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 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\&.3 tcllib "CGI Support" +.TH "ncgi" n 1\&.4\&.4 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\&.3?\fR +package require \fBncgi ?1\&.4\&.4?\fR .sp \fB::ncgi::cookie\fR \fIcookie\fR .sp \fB::ncgi::decode\fR \fIstr\fR .sp 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\&.2 tcllib "oauth" +.TH "oauth" n 1\&.0\&.3 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\&.2?\fR +package require \fBoauth ?1\&.0\&.3?\fR .sp \fB::oauth::config\fR .sp \fB::oauth::config\fR ?\fIoptions\fR\&.\&.\&.? .sp Index: idoc/man/files/modules/pki/pki.n ================================================================== --- idoc/man/files/modules/pki/pki.n +++ idoc/man/files/modules/pki/pki.n @@ -347,20 +347,39 @@ .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\&. 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\&. +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 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? Index: idoc/man/files/modules/pop3/pop3.n ================================================================== --- idoc/man/files/modules/pop3/pop3.n +++ idoc/man/files/modules/pop3/pop3.n @@ -501,11 +501,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 +519,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 Index: idoc/man/files/modules/pop3d/pop3d.n ================================================================== --- idoc/man/files/modules/pop3d/pop3d.n +++ idoc/man/files/modules/pop3d/pop3d.n @@ -491,11 +491,11 @@ command, see package \fBtls\fR, to secure the communication\&. .CS package require tls - tls::init \\\\ + tls::init \\ \&.\&.\&. pop3d::new S -socket tls::socket \&.\&.\&. 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 '\" -.TH "practcl" n 0\&.11 tcllib "The The Proper Rational API for C to Tool Command Language Module" +.TH "practcl" n 0\&.16\&.4 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,69 +274,1882 @@ .SH NAME practcl \- The Practcl Module .SH SYNOPSIS package require \fBTclOO 1\&.0\fR .sp -package require \fBpractcl 0\&.11\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? +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 .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 -\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? +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 -.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 +\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 .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 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\&.3 tcllib "Tcl Profiler" +.TH "profiler" n 0\&.5 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\&.3?\fR +package require \fBprofiler ?0\&.5?\fR .sp \fB::profiler::init\fR .sp \fB::profiler::dump\fR \fIpattern\fR .sp @@ -286,10 +286,14 @@ \fB::profiler::reset\fR ?\fIpattern\fR? .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 @@ -363,10 +367,22 @@ 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 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 tcllib "Parser Tools" +.TH "pt::peg::export" n 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. @@ -276,17 +276,17 @@ .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp package require \fBsnit \fR .sp -package require \fBconfiguration \fR +package require \fBstruct::map \fR .sp package require \fBpt::peg \fR .sp package require \fBpluginmgr \fR .sp -package require \fBpt::peg::export ?1?\fR +package require \fBpt::peg::export ?1\&.0\&.1?\fR .sp \fB::pt::peg::export\fR \fIobjectName\fR .sp \fBobjectName\fR \fBmethod\fR ?\fIarg arg \&.\&.\&.\fR? .sp 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 tcllib "Parser Tools" +.TH "pt::peg::import" n 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,19 +274,21 @@ .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 \fBconfiguration \fR +package require \fBfileutil::paths \fR .sp package require \fBpt::peg \fR .sp package require \fBpluginmgr \fR .sp -package require \fBpt::peg::import ?1?\fR +package require \fBpt::peg::import ?1\&.0\&.1?\fR .sp \fB::pt::peg::import\fR \fIobjectName\fR .sp \fBobjectName\fR \fBmethod\fR ?\fIarg arg \&.\&.\&.\fR? .sp 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\&.3 tcllib "SHA-x Message-Digest Algorithm" +.TH "sha1" n 2\&.0\&.4 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\&.3?\fR +package require \fBsha1 ?2\&.0\&.4?\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 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\&.3 tcllib "SHA-x Message-Digest Algorithm" +.TH "sha256" n 1\&.0\&.4 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\&.3?\fR +package require \fBsha256 ?1\&.0\&.4?\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 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\&.1 tcllib "Tcl Simulation Tools" +.TH "simulation::random" n 0\&.4 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,20 +274,24 @@ .SH NAME simulation::random \- Pseudo-random number generators .SH SYNOPSIS package require \fBTcl ?8\&.4?\fR .sp -package require \fBsimulation::random 0\&.1\fR +package require \fBsimulation::random 0\&.4\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 @@ -364,10 +368,38 @@ .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/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 Andreas Kupries +'\" Copyright (c) 2002-2009,2019 Andreas Kupries '\" -.TH "struct::graph" n 2\&.4\&.1 tcllib "Tcl Data Structures" +.TH "struct::graph" n 2\&.4\&.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::graph \- Create and manipulate directed graph objects .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBstruct::graph ?2\&.4\&.1?\fR +package require \fBstruct::graph ?2\&.4\&.3?\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-embedded\fR are applied +\fB-adj\fR, \fB-inner\fR, or \fB-embedding\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,10 +764,21 @@ .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 @@ -894,13 +905,17 @@ 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\&. The exact meanings change slightly, as they operate on -nodes instead of arcs\&. The command recognizes: +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: .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 @@ -1033,14 +1048,14 @@ # A possible serialization for the graph structure # # d -----> %2 - # / ^ \\\\ - # / / \\\\ - # / b \\\\ - # / / \\\\ + # / ^ \\ + # / / \\ + # / b \\ + # / / \\ # %1 <- a - %0 e # ^ \\\\ / # \\\\ c / # \\\\ \\\\ / # \\\\ v v @@ -1162,8 +1177,8 @@ adjacent, arc, cgraph, degree, edge, graph, loop, neighbour, node, serialization, subgraph, vertex .SH CATEGORY Data structures .SH COPYRIGHT .nf -Copyright (c) 2002-2009 Andreas Kupries +Copyright (c) 2002-2009,2019 Andreas Kupries .fi 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 Andreas Kupries +'\" Copyright (c) 2002-2013,2019 Andreas Kupries '\" -.TH "struct::matrix" n 2\&.0\&.3 tcllib "Tcl Data Structures" +.TH "struct::matrix" n 2\&.0\&.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::matrix \- Create and manipulate matrix objects .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBstruct::matrix ?2\&.0\&.3?\fR +package require \fBstruct::matrix ?2\&.0\&.4?\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 @@ -848,8 +848,8 @@ matrix .SH CATEGORY Data structures .SH COPYRIGHT .nf -Copyright (c) 2002-2013 Andreas Kupries +Copyright (c) 2002-2013,2019 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 Andreas Kupries +'\" Copyright (c) 2002,2019 Andreas Kupries '\" -.TH "struct::matrix_v1" n 1\&.2\&.1 tcllib "Tcl Data Structures" +.TH "struct::matrix_v1" n 1\&.2\&.2 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\&.1?\fR +package require \fBstruct::matrix ?1\&.2\&.2?\fR .sp \fBmatrixName\fR \fIoption\fR ?\fIarg arg \&.\&.\&.\fR? .sp \fImatrixName\fR \fBadd column\fR ?\fIvalues\fR? .sp @@ -684,8 +684,8 @@ matrix .SH CATEGORY Data structures .SH COPYRIGHT .nf -Copyright (c) 2002 Andreas Kupries +Copyright (c) 2002,2019 Andreas Kupries .fi 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\&.1 tcllib "Tcl Data Structures" +.TH "struct::record" n 1\&.2\&.2 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\&.1?\fR +package require \fBstruct::record ?1\&.2\&.2?\fR .sp \fBrecord define\fR \fIrecordName\fR \fIrecordMembers\fR ?\fIinstanceName1 instanceName2 \&.\&.\&.\fR? .sp \fBrecord show\fR \fIrecord\fR .sp @@ -294,50 +294,67 @@ .sp \fBrecord delete\fR \fIrecord\fR \fIrecordName\fR .sp \fBrecord delete\fR \fIinstance\fR \fIinstanceName\fR .sp -\fIrecordName\fR \fB\fIinstanceName|#auto\fR\fR ?\fI-member1 value1 -member2 value2 \&.\&.\&.\fR? +\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? .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 '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\&. +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\&. .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\&. \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\&. +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\&. .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 @@ -350,24 +367,25 @@ \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\&. -.PP +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\&. .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\&. For example, it would look like this: +nested record (within the container)\&. For example, it would look like +this: .PP .CS # this is the nested record @@ -381,167 +399,182 @@ 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 -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: +.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 +% # Create an instance first % myrecord inst1 ::inst1 -% # To get a member of an instance, just use the -% # alias (it behaves like a Tcl command): + +% # 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) + +% # 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) + +% # 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 + +% # 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: +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\&. +\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, \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\&. +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\&. .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 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\&. +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\&. .TP \fIinstanceName\fR \fBconfigure\fR ?\fI-member1 value1 -member2 value2 \&.\&.\&.\fR? -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\&. +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\&. .PP .SH EXAMPLES -Two examples are provided to give an good illustration on how to use +Two examples are provided to give a good illustration on how to use this package\&. -.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: +.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 .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'\&. @@ -590,50 +623,45 @@ % record show members contacts first middle last {record locations home} {record locations work} % .CE -.PP -\fIExample 1\fR -.PP +.SS "EXAMPLE 2 - LINKED LIST" This next example just illustrates a simple linked list .PP .CS - % # define a very simple record for linked list -% record define llist { +% record define linkedlist { value next } -::llist -% llist lstart +::linkedlist +% linkedlist lstart ::lstart -% lstart config -value 1 -next [llist #auto] -% [lstart cget -next] config -value 2 -next [llist #auto] +% 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} + 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 +% # We could just use delete record linkedlist also +% foreach I [record show instances linkedlist] { + record delete instance $I } -% record show instances llist +% record show instances linkedlist % - .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]\&. ADDED idoc/man/files/modules/struct/struct_map.n Index: idoc/man/files/modules/struct/struct_map.n ================================================================== --- /dev/null +++ idoc/man/files/modules/struct/struct_map.n @@ -0,0 +1,349 @@ +'\" +'\" 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\&. ADDED idoc/man/files/modules/textutil/patch.n Index: idoc/man/files/modules/textutil/patch.n ================================================================== --- /dev/null +++ idoc/man/files/modules/textutil/patch.n @@ -0,0 +1,345 @@ +'\" +'\" 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/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 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 tcllib "Reflected/virtual channel support" +.TH "tcl::chan::cat" n 1\&.0\&.3 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?\fR +package require \fBtcl::chan::cat ?1\&.0\&.3?\fR .sp \fB::tcl::chan::cat\fR \fIchan\fR\&.\&.\&. .sp .BE .SH DESCRIPTION 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 Andreas Kupries +'\" Copyright (c) 2009, 2019 Andreas Kupries '\" -.TH "tcl::chan::halfpipe" n 1 tcllib "Reflected/virtual channel support" +.TH "tcl::chan::halfpipe" n 1\&.0\&.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,13 +278,11 @@ .sp package require \fBTclOO \fR .sp package require \fBtcl::chan::events ?1?\fR .sp -package require \fBtcl::chan::halfpipe ?1?\fR -.sp -package require \fBtcl::chan::halfpipe ?1?\fR +package require \fBtcl::chan::halfpipe ?1\&.0\&.1?\fR .sp \fB::tcl::chan::halfpipe\fR ?\fB-option\fR \fIvalue\fR\&.\&.\&.? .sp \fIobjectCmd\fR \fBput\fR \fIbytes\fR .sp @@ -353,8 +351,8 @@ callbacks, fifo, in-memory channel, reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf -Copyright (c) 2009 Andreas Kupries +Copyright (c) 2009, 2019 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 tcllib "Zip archive creation" +.TH "zipfile::mkzip" n 1\&.2\&.1 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?\fR +package require \fBzipfile::mkzip ?1\&.2\&.1?\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 Index: idoc/man/index.n ================================================================== --- idoc/man/index.n +++ idoc/man/index.n @@ -1472,10 +1472,16 @@ \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 @@ -1485,13 +1491,10 @@ oometa .TP \fBfiles/modules/tool/tool\&.n\fR tool .TP -\fBfiles/modules/httpd/httpd\&.n\fR -tool -.TP \fBfiles/modules/tool/tool_dict_ensemble\&.n\fR tool::dict_ensemble .RE TeX .RS @@ -1702,11 +1705,11 @@ .RE WWW .RS .TP \fBfiles/modules/httpd/httpd\&.n\fR -tool +httpd .RE XGoogleToken .RS .TP \fBfiles/modules/sasl/gtoken\&.n\fR @@ -3522,10 +3525,22 @@ .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 @@ -4803,10 +4818,16 @@ doctoc_plugin_apiref .TP \fBfiles/modules/doctools/doctools_plugin_apiref\&.n\fR doctools_plugin_apiref .RE +fossil +.RS +.TP +\fBfiles/modules/textutil/patch\&.n\fR +textutil::patch +.RE frame .RS .TP \fBfiles/modules/term/ansi_cmacros\&.n\fR term::ansi::code::macros @@ -4917,10 +4938,16 @@ 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 @@ -5264,20 +5291,20 @@ http .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 .TP -\fBfiles/modules/httpd/httpd\&.n\fR -tool -.TP \fBfiles/modules/uri/uri\&.n\fR uri .TP \fBfiles/modules/websocket/websocket\&.n\fR websocket @@ -5284,11 +5311,11 @@ .RE httpd .RS .TP \fBfiles/modules/httpd/httpd\&.n\fR -tool +httpd .RE https .RS .TP \fBfiles/modules/uri/uri\&.n\fR @@ -5296,11 +5323,11 @@ .RE httpserver .RS .TP \fBfiles/modules/httpd/httpd\&.n\fR -tool +httpd .RE huddle .RS .TP \fBfiles/modules/yaml/huddle\&.n\fR @@ -6605,10 +6632,13 @@ mathematics .RS .TP \fBfiles/modules/math/fourier\&.n\fR math::fourier +.TP +\fBfiles/modules/math/quasirandom\&.n\fR +math::quasirandom .TP \fBfiles/modules/math/statistics\&.n\fR math::statistics .RE matrices @@ -7281,10 +7311,16 @@ .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 optimization .RS .TP \fBfiles/modules/math/optimize\&.n\fR math::optimize @@ -7937,10 +7973,13 @@ 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 @@ -8412,10 +8451,16 @@ 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 @@ -9581,16 +9626,16 @@ services .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 -.TP -\fBfiles/modules/httpd/httpd\&.n\fR -tool .RE set .RS .TP \fBfiles/modules/struct/queue\&.n\fR @@ -11270,10 +11315,16 @@ \fBfiles/modules/stringprep/unicode\&.n\fR 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 Index: idoc/man/toc.n ================================================================== --- idoc/man/toc.n +++ idoc/man/toc.n @@ -331,10 +331,13 @@ \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 ISO 8601 dates/times @@ -622,10 +625,13 @@ \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 @@ -694,10 +700,13 @@ \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 @@ -826,10 +835,13 @@ \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::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 @@ -1198,10 +1210,13 @@ \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 @@ -1330,22 +1345,40 @@ \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 +.TP \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 @@ -1402,10 +1435,13 @@ \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 @@ -1432,13 +1468,10 @@ \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 .TP -\fBtool\fR -\fIfiles/modules/httpd/httpd\&.n\fR: A TclOO and coroutine based web server -.TP \fBtool::dict_ensemble\fR \fIfiles/modules/tool/tool_dict_ensemble\&.n\fR: Dictionary Tools .TP \fBtransfer::connect\fR \fIfiles/modules/transfer/connect\&.n\fR: Connection setup Index: idoc/www/index.html ================================================================== --- idoc/www/index.html +++ idoc/www/index.html @@ -1018,10 +1018,20 @@ diff -n format rcs + + diff -ruN + + textutil::patch + + + diff, unified format + + textutil::patch + difference struct::set @@ -1525,97 +1535,107 @@ 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 @@ -1723,26 +1743,26 @@ html · htmlparse · javascript · ncgi http - autoproxy · map::geocode::nominatim · map::slippy::fetcher · tool · uri · websocket + autoproxy · httpd · map::geocode::nominatim · map::slippy::fetcher · uri · websocket httpd - tool + httpd https uri httpserver - tool + httpd huddle huddle · yaml @@ -2273,11 +2293,11 @@ 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::statistics + math::fourier · math::quasirandom · math::statistics matrices math::linearalgebra @@ -2622,320 +2642,330 @@ one time pad tcl::transform::otp + oo + + clay + + 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 + 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 - + 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 @@ -3441,11 +3471,11 @@ logger services - ftpd · smtpd · tool + ftpd · httpd · smtpd set struct::queue · struct::set @@ -3794,11 +3824,11 @@ csv TclOO - oo::util · oo::util · oometa · tool · tool · tool::dict_ensemble + clay · httpd · oo::util · oo::util · oometa · tool · tool::dict_ensemble TCLPARAM pt::peg::to::tclparam @@ -4120,246 +4150,251 @@ 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 - tool + 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 map::slippy · map::slippy::cache · map::slippy::fetcher ADDED idoc/www/tcllib/files/devdoc/tcl_community_communication.html Index: idoc/www/tcllib/files/devdoc/tcl_community_communication.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/devdoc/tcl_community_communication.html @@ -0,0 +1,251 @@ + +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

+
+
+
ADDED idoc/www/tcllib/files/devdoc/tcllib_devguide.html Index: idoc/www/tcllib/files/devdoc/tcllib_devguide.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/devdoc/tcllib_devguide.html @@ -0,0 +1,982 @@ + +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.

+
+
ADDED idoc/www/tcllib/files/devdoc/tcllib_installer.html Index: idoc/www/tcllib/files/devdoc/tcllib_installer.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/devdoc/tcllib_installer.html @@ -0,0 +1,392 @@ + +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 installed by +default.

+

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 # This builds the shared library holding
+              # the accelerators
+  make install
+
+

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.

+
+
+
+
ADDED idoc/www/tcllib/files/devdoc/tcllib_license.html Index: idoc/www/tcllib/files/devdoc/tcllib_license.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/devdoc/tcllib_license.html @@ -0,0 +1,162 @@ + +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.

+
+
ADDED idoc/www/tcllib/files/devdoc/tcllib_releasemgr.html Index: idoc/www/tcllib/files/devdoc/tcllib_releasemgr.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/devdoc/tcllib_releasemgr.html @@ -0,0 +1,199 @@ + +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. +
+
+
+
ADDED idoc/www/tcllib/files/devdoc/tcllib_sources.html Index: idoc/www/tcllib/files/devdoc/tcllib_sources.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/devdoc/tcllib_sources.html @@ -0,0 +1,169 @@ + +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.

+
+
ADDED idoc/www/tcllib/files/modules/clay/clay.html Index: idoc/www/tcllib/files/modules/clay/clay.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/modules/clay/clay.html @@ -0,0 +1,719 @@ + +clay - Clay Framework + + + + + +
[ + Tcllib Home +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

clay(n) 0.8.6 tcllib "Clay Framework"

+

Name

+

clay - A minimalist framework for large scale OO Projects

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require uuid
    • +
  • package require oo::dialect
    • +
+ +
+
+

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 <counter> $obj
+  }
+  method line {text} {
+    my <counter> incr
+    append buffer $text
+  }
+}
+set A [example new]
+$A line {Who’s line is it anyway?}
+$A <counter> 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.

+
+
+
+ +

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. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+

When proposing code changes, please provide unified diffs, +i.e the output of diff -u.

+

Note further that attachments are strongly preferred over +inlined patches. Attachments can be made by 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/debug/debug_heartbeat.html ================================================================== --- idoc/www/tcllib/files/modules/debug/debug_heartbeat.html +++ idoc/www/tcllib/files/modules/debug/debug_heartbeat.html @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
-

debug::heartbeat(n) 1 tcllib "debug narrative"

+

debug::heartbeat(n) 1.0.1 tcllib "debug narrative"

Name

debug::heartbeat - debug narrative - heartbeat

Table Of Contents

    @@ -125,11 +125,11 @@

Synopsis

  • package require Tcl 8.5
    • -
  • package require debug::heartbeat ?1?
    • +
  • package require debug::heartbeat ?1.0.1?
  • package require debug ?1?
  • debug heartbeat ?delta?
Index: idoc/www/tcllib/files/modules/dicttool/dicttool.html ================================================================== --- idoc/www/tcllib/files/modules/dicttool/dicttool.html +++ idoc/www/tcllib/files/modules/dicttool/dicttool.html @@ -124,10 +124,11 @@

Synopsis

  • package require Tcl 8.5
    • +
  • package require dicttool ?1.0?
  • ladd varname args
  • ldelete varname args
  • dict getnull args
    • @@ -145,11 +146,11 @@
    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.

    +

    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 Index: idoc/www/tcllib/files/modules/dns/tcllib_dns.html ================================================================== --- idoc/www/tcllib/files/modules/dns/tcllib_dns.html +++ idoc/www/tcllib/files/modules/dns/tcllib_dns.html @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]

    -

    dns(n) 1.4.0 tcllib "Domain Name Service"

    +

    dns(n) 1.4.1 tcllib "Domain Name Service"

    Name

    dns - Tcl Domain Name Service Client

    Table Of Contents

      @@ -129,11 +129,11 @@

    Synopsis

    • package require Tcl 8.2
      • -
    • package require dns ?1.4.0?
      • +
    • package require dns ?1.4.1?
    • ::dns::resolve query ?options?
    • ::dns::configure ?options?
    • ::dns::name token
      • Index: idoc/www/tcllib/files/modules/doctools/docidx_lang_intro.html ================================================================== --- idoc/www/tcllib/files/modules/doctools/docidx_lang_intro.html +++ idoc/www/tcllib/files/modules/doctools/docidx_lang_intro.html @@ -148,11 +148,11 @@ commands, continuation lines, etc. I.e.

           ... [key {markup language}] ...
 
      -  ... [manpage thefile \\
+  ... [manpage thefile \
           {file description}] ...

    Basic structure

    The most simple document which can be written in docidx is

    Index: idoc/www/tcllib/files/modules/doctools/doctoc_lang_intro.html ================================================================== --- idoc/www/tcllib/files/modules/doctools/doctoc_lang_intro.html +++ idoc/www/tcllib/files/modules/doctools/doctoc_lang_intro.html @@ -150,11 +150,11 @@ commands, continuation lines, etc. I.e.

         ... [division_start {Appendix 1}] ...
 
    -  ... [item thefile \\
+  ... [item thefile \
           label {file description}] ...

    Basic structure

    The most simple document which can be written in doctoc is

    Index: idoc/www/tcllib/files/modules/doctools/doctools.html ================================================================== --- idoc/www/tcllib/files/modules/doctools/doctools.html +++ idoc/www/tcllib/files/modules/doctools/doctools.html @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
    -

    doctools(n) 1.5.1 tcllib "Documentation tools"

    +

    doctools(n) 1.5.6 tcllib "Documentation tools"

    Name

    doctools - doctools - Processing documents

    Table Of Contents

      @@ -135,11 +135,11 @@

    Synopsis

    • package require Tcl 8.2
      • -
    • package require doctools ?1.5.1?
      • +
    • package require doctools ?1.5.6?
    • ::doctools::new objectName ?option value...?
    • ::doctools::help
    • ::doctools::search path
      • Index: idoc/www/tcllib/files/modules/doctools/doctools_lang_intro.html ================================================================== --- idoc/www/tcllib/files/modules/doctools/doctools_lang_intro.html +++ idoc/www/tcllib/files/modules/doctools/doctools_lang_intro.html @@ -152,11 +152,11 @@ commands, continuation lines, etc. I.e.

         ... [list_begin enumerated] ...
 
      -  ... [call [cmd foo] \\
+  ... [call [cmd foo] \
           [arg bar]] ...
 
         ... [term {complex concept}] ...
      @@ -178,11 +178,11 @@ [keywords {doctools syntax}] [keywords markup] [keywords {semantic markup}] [description] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[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 @@ -229,11 +229,11 @@ 

           [manpage_begin NAME SECTION VERSION]
     [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
     [require PACKAGE VERSION][require PACKAGE][description]
     [vset CATEGORY doctools]
-[include ../doctools2base/include/feedback.inc]
+[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, Index: idoc/www/tcllib/files/modules/doctools2idx/export_docidx.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2idx/export_docidx.html +++ idoc/www/tcllib/files/modules/doctools2idx/export_docidx.html @@ -91,11 +91,11 @@ } --> -

      [ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
      -

      doctools::idx::export::docidx(n) 0.1 tcllib "Documentation tools"

      +

      doctools::idx::export::docidx(n) 0.2.1 tcllib "Documentation tools"

      Name

      doctools::idx::export::docidx - docidx export plugin

      Table Of Contents

        @@ -128,11 +128,11 @@

      Synopsis

      • package require Tcl 8.4
        • -
      • package require doctools::idx::export::docidx ?0.1?
        • +
      • package require doctools::idx::export::docidx ?0.2.1?
      @@ -302,8 +302,8 @@

      Category

      Text formatter plugin

      Index: idoc/www/tcllib/files/modules/doctools2idx/idx_export.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2idx/idx_export.html +++ idoc/www/tcllib/files/modules/doctools2idx/idx_export.html @@ -91,11 +91,11 @@ } --> -
      [ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
      -

      doctools::idx::export(n) 0.2 tcllib "Documentation tools"

      +

      doctools::idx::export(n) 0.2.1 tcllib "Documentation tools"

      Name

      doctools::idx::export - Exporting keyword indices

      Table Of Contents

        @@ -133,13 +133,13 @@

      Synopsis

        -
      • package require doctools::idx::export ?0.2?
        • +
      • package require doctools::idx::export ?0.2.1?
      • package require Tcl 8.4
        • -
      • package require doctools::config
        • +
      • package require struct::map
      • package require doctools::idx::structure
      • package require snit
      • package require pluginmgr
        @@ -460,8 +460,8 @@

      Category

      Documentation tools

      Index: idoc/www/tcllib/files/modules/doctools2idx/idx_export_html.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2idx/idx_export_html.html +++ idoc/www/tcllib/files/modules/doctools2idx/idx_export_html.html @@ -91,11 +91,11 @@ } --> -
      [ Tcllib Home @@ -364,8 +364,8 @@

      Category

      Text formatter plugin

    Index: idoc/www/tcllib/files/modules/doctools2idx/idx_export_json.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2idx/idx_export_json.html +++ idoc/www/tcllib/files/modules/doctools2idx/idx_export_json.html @@ -91,11 +91,11 @@ } --> -
    [ Tcllib Home @@ -317,8 +317,8 @@

    Category

    Text formatter plugin

    Index: idoc/www/tcllib/files/modules/doctools2idx/idx_export_nroff.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2idx/idx_export_nroff.html +++ idoc/www/tcllib/files/modules/doctools2idx/idx_export_nroff.html @@ -91,11 +91,11 @@ } --> -
    [ Tcllib Home @@ -271,8 +271,8 @@

    Category

    Text formatter plugin

    Index: idoc/www/tcllib/files/modules/doctools2idx/idx_export_text.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2idx/idx_export_text.html +++ idoc/www/tcllib/files/modules/doctools2idx/idx_export_text.html @@ -91,11 +91,11 @@ } --> -
    [ Tcllib Home @@ -258,8 +258,8 @@

    Category

    Text formatter plugin

Index: idoc/www/tcllib/files/modules/doctools2idx/idx_export_wiki.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2idx/idx_export_wiki.html +++ idoc/www/tcllib/files/modules/doctools2idx/idx_export_wiki.html @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -271,8 +271,8 @@

Category

Text formatter plugin

Index: idoc/www/tcllib/files/modules/doctools2idx/idx_import.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2idx/idx_import.html +++ idoc/www/tcllib/files/modules/doctools2idx/idx_import.html @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
-

doctools::idx::import(n) 0.2 tcllib "Documentation tools"

+

doctools::idx::import(n) 0.2.1 tcllib "Documentation tools"

Name

doctools::idx::import - Importing keyword indices

Table Of Contents

    @@ -133,13 +133,13 @@

Synopsis

    -
  • package require doctools::idx::import ?0.2?
    • +
  • package require doctools::idx::import ?0.2.1?
  • package require Tcl 8.4
    • -
  • package require doctools::config
    • +
  • package require struct::map
  • package require doctools::idx::structure
  • package require snit
  • package require pluginmgr
    @@ -519,8 +519,8 @@

Category

Documentation tools

Index: idoc/www/tcllib/files/modules/doctools2idx/idx_import_json.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2idx/idx_import_json.html +++ idoc/www/tcllib/files/modules/doctools2idx/idx_import_json.html @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
-

doctools::idx::import::json(n) 0.1 tcllib "Documentation tools"

+

doctools::idx::import::json(n) 0.2.1 tcllib "Documentation tools"

Name

doctools::idx::import::json - JSON import plugin

Table Of Contents

    @@ -126,12 +126,12 @@

Synopsis

    -
  • package require Tcl 8.4
    • -
  • package require doctools::idx::import::json ?0.1?
    • +
  • package require Tcl 8.5
    • +
  • package require doctools::idx::import::json ?0.2.1?
  • package require doctools::idx::structure
  • package require json
  • import string configuration
    • @@ -294,8 +294,8 @@

Category

Text formatter plugin

Index: idoc/www/tcllib/files/modules/doctools2idx/idx_introduction.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2idx/idx_introduction.html +++ idoc/www/tcllib/files/modules/doctools2idx/idx_introduction.html @@ -208,17 +208,17 @@ ~~ | ~~ doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import | | | +---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+ | | | | | | | | | -doctools::config = | | | = doctools::include doctools::config doctools::paths +struct::map = | | | = doctools::include struct::map fileutil::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 | | +-------+---------------+ Index: idoc/www/tcllib/files/modules/doctools2idx/import_docidx.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2idx/import_docidx.html +++ idoc/www/tcllib/files/modules/doctools2idx/import_docidx.html @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
-

doctools::idx::import::docidx(n) 0.1 tcllib "Documentation tools"

+

doctools::idx::import::docidx(n) 0.2.1 tcllib "Documentation tools"

Name

doctools::idx::import::docidx - docidx import plugin

Table Of Contents

    @@ -126,12 +126,12 @@

Synopsis

    -
  • package require Tcl 8.4
    • -
  • package require doctools::idx::import::docidx ?0.1?
    • +
  • 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
    • @@ -271,8 +271,8 @@

Category

Text formatter plugin

Index: idoc/www/tcllib/files/modules/doctools2toc/export_doctoc.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/export_doctoc.html +++ idoc/www/tcllib/files/modules/doctools2toc/export_doctoc.html @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
-

doctools::toc::export::doctoc(n) 0.1 tcllib "Documentation tools"

+

doctools::toc::export::doctoc(n) 0.2.1 tcllib "Documentation tools"

Name

doctools::toc::export::doctoc - doctoc export plugin

Table Of Contents

    @@ -128,11 +128,11 @@

Synopsis

  • package require Tcl 8.4
    • -
  • package require doctools::toc::export::doctoc ?0.1?
    • +
  • package require doctools::toc::export::doctoc ?0.2.1?
@@ -325,8 +325,8 @@

Category

Text formatter plugin

Index: idoc/www/tcllib/files/modules/doctools2toc/import_doctoc.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/import_doctoc.html +++ idoc/www/tcllib/files/modules/doctools2toc/import_doctoc.html @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
-

doctools::toc::import::doctoc(n) 0.1 tcllib "Documentation tools"

+

doctools::toc::import::doctoc(n) 0.2.1 tcllib "Documentation tools"

Name

doctools::toc::import::doctoc - doctoc import plugin

Table Of Contents

    @@ -126,12 +126,12 @@

Synopsis

    -
  • package require Tcl 8.4
    • -
  • package require doctools::toc::import::doctoc ?0.1?
    • +
  • 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
    • @@ -295,8 +295,8 @@

Category

Text formatter plugin

Index: idoc/www/tcllib/files/modules/doctools2toc/toc_export.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_export.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_export.html @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
-

doctools::toc::export(n) 0.2 tcllib "Documentation tools"

+

doctools::toc::export(n) 0.2.1 tcllib "Documentation tools"

Name

doctools::toc::export - Exporting tables of contents

Table Of Contents

    @@ -133,13 +133,13 @@

Synopsis

    -
  • package require doctools::toc::export ?0.2?
    • +
  • package require doctools::toc::export ?0.2.1?
  • package require Tcl 8.4
    • -
  • package require doctools::config
    • +
  • package require struct::map
  • package require doctools::toc::structure
  • package require snit
  • package require pluginmgr
    @@ -476,8 +476,8 @@

Category

Documentation tools

Index: idoc/www/tcllib/files/modules/doctools2toc/toc_export_html.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_export_html.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_export_html.html @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -358,8 +358,8 @@

Category

Text formatter plugin

Index: idoc/www/tcllib/files/modules/doctools2toc/toc_export_json.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_export_json.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_export_json.html @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -361,8 +361,8 @@

Category

Text formatter plugin

Index: idoc/www/tcllib/files/modules/doctools2toc/toc_export_nroff.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_export_nroff.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_export_nroff.html @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -295,8 +295,8 @@

Category

Text formatter plugin

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 @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -281,8 +281,8 @@

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 @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -288,8 +288,8 @@

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 @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
-

doctools::toc::import(n) 0.2 tcllib "Documentation tools"

+

doctools::toc::import(n) 0.2.1 tcllib "Documentation tools"

Name

doctools::toc::import - Importing keyword indices

Table Of Contents

    @@ -133,13 +133,13 @@

Synopsis

    -
  • package require doctools::toc::import ?0.2?
    • +
  • package require doctools::toc::import ?0.2.1?
  • package require Tcl 8.4
    • -
  • package require doctools::config
    • +
  • package require struct::map
  • package require doctools::toc::structure
  • package require snit
  • package require pluginmgr
    @@ -537,8 +537,8 @@

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 @@ -91,11 +91,11 @@ } --> -
[ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
-

doctools::toc::import::json(n) 0.1 tcllib "Documentation tools"

+

doctools::toc::import::json(n) 0.2.1 tcllib "Documentation tools"

Name

doctools::toc::import::json - JSON import plugin

Table Of Contents

    @@ -126,12 +126,12 @@

Synopsis

    -
  • package require Tcl 8.4
    • -
  • package require doctools::toc::import::json ?0.1?
    • +
  • package require Tcl 8.5
    • +
  • package require doctools::toc::import::json ?0.2.1?
  • package require doctools::toc::structure
  • package require json
  • import string configuration
    • @@ -338,8 +338,8 @@

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 @@ -208,17 +208,17 @@ ~~ | ~~ doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import | | | +---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+ | | | | | | | | | -doctools::config = | | | = doctools::include doctools::config doctools::paths +struct:map = | | | = doctools::include struct::map fileutil::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 | | +-------+---------------+ 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 @@ -383,47 +383,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 +431,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 ADDED idoc/www/tcllib/files/modules/fileutil/paths.html Index: idoc/www/tcllib/files/modules/fileutil/paths.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/modules/fileutil/paths.html @@ -0,0 +1,190 @@ + +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/grammar_fa/fa.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_fa/fa.html +++ idoc/www/tcllib/files/modules/grammar_fa/fa.html @@ -311,15 +311,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 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 @@ -348,24 +348,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.

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 @@ -103,11 +103,11 @@ | Categories | Modules | Applications ]
-

html(n) 1.4.4 tcllib "HTML Generation"

+

html(n) 1.5 tcllib "HTML Generation"

Name

html - Procedures to generate HTML structures

Table Of Contents

    @@ -122,11 +122,11 @@

Synopsis

  • package require Tcl 8.2
    • -
  • package require html ?1.4.4?
    • +
  • package require html ?1.5?

Description

The package html provides commands that generate HTML. @@ -339,141 +343,163 @@ 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 +

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
+
::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?
+
::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
+
::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
+
::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?
+
::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 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?
+
::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?
+
::html::textarea name ?param? ?current?

Generate a textarea tag wrapped around its current values.

-
::html::textInput name value args
+
::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
+
::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:

    @@ -488,10 +514,16 @@

  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. 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,7 +1,7 @@ -tool - Tcl Web Server +httpd - Tcl Web Server + + + +

[ + Tcllib Home +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::quasirandom(n) 1 tcllib "Tcl Math Library"

+

Name

+

math::quasirandom - Quasi-random points for integration and Monte Carlo type methods

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require math::quasirandom 1
    • +
+ +
+
+

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 "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/

+
+ +

Category

+

Mathematics

+
+
Index: idoc/www/tcllib/files/modules/math/special.html ================================================================== --- idoc/www/tcllib/files/modules/math/special.html +++ idoc/www/tcllib/files/modules/math/special.html @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
-

math::special(n) 0.3 tcllib "Tcl Math Library"

+

math::special(n) 0.4 tcllib "Tcl Math Library"

Name

math::special - Special mathematical functions

Table Of Contents

    @@ -127,44 +127,47 @@

Synopsis

    -
  • package require Tcl ?8.3?
    • -
  • package require math::special ?0.3?
    • +
  • package require Tcl ?8.5?
    • +
  • package require math::special ?0.4?

Description

This package implements several so-called special functions, like @@ -224,10 +227,15 @@ 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 @@ -241,12 +249,11 @@

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

    • +

  • The incomplete gamma function

PROCEDURES

The package defines the following public procedures:

@@ -256,208 +263,234 @@
float x

First argument for the Beta function

float y

Second argument for the Beta function

-
::math::special::Gamma x
+
::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::erf x
+
::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
+
::math::special::erfc x

Compute the complementary error function for argument "x"

float x

Argument for the complementary error function

-
::math::special::invnorm p
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::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
+
::math::special::fresnel_S x

Compute the Fresnel sine integral for real argument x

float x

Argument for the function

-
::math::special::sinc x
+
::math::special::sinc x

Compute the sinc function for real argument x

float x

Argument for the function

-
::math::special::legendre n
+
::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
+
::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
+
::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
+
::math::special::hermite n

Return the Hermite polynomial of degree n

int n

Degree of the polynomial

Index: idoc/www/tcllib/files/modules/math/statistics.html ================================================================== --- idoc/www/tcllib/files/modules/math/statistics.html +++ idoc/www/tcllib/files/modules/math/statistics.html @@ -168,78 +168,98 @@
  • ::math::statistics::control-Rchart data ?nsamples?
  • ::math::statistics::test-xbar control data
  • ::math::statistics::test-Rchart control data
  • ::math::statistics::test-Kruskal-Wallis confidence args
  • ::math::statistics::analyse-Kruskal-Wallis args
    • -
  • ::math::statistics::group-rank args
    • -
  • ::math::statistics::test-Wilcoxon sample_a sample_b
    • -
  • ::math::statistics::spearman-rank sample_a sample_b
    • -
  • ::math::statistics::spearman-rank-extended sample_a sample_b
    • -
  • ::math::statistics::kernel-density data opt -option value ...
    • -
  • ::math::statistics::bootstrap data sampleSize ?numberSamples?
    • -
  • ::math::statistics::wasserstein-distance prob1 prob2
    • -
  • ::math::statistics::kl-divergence prob1 prob2
    • -
  • ::math::statistics::logistic-model xdata ydata
    • -
  • ::math::statistics::logistic-probability coeffs x
    • -
  • ::math::statistics::tstat dof ?alpha?
    • -
  • ::math::statistics::mv-wls wt1 weights_and_values
    • -
  • ::math::statistics::mv-ols values
    • -
  • ::math::statistics::pdf-normal mean stdev value
    • -
  • ::math::statistics::pdf-lognormal mean stdev value
    • -
  • ::math::statistics::pdf-exponential mean value
    • -
  • ::math::statistics::pdf-uniform xmin xmax value
    • -
  • ::math::statistics::pdf-gamma alpha beta value
    • -
  • ::math::statistics::pdf-poisson mu k
    • -
  • ::math::statistics::pdf-chisquare df value
    • -
  • ::math::statistics::pdf-student-t df value
    • -
  • ::math::statistics::pdf-gamma a b value
    • -
  • ::math::statistics::pdf-beta a b value
    • -
  • ::math::statistics::pdf-weibull scale shape value
    • -
  • ::math::statistics::pdf-gumbel location scale value
    • -
  • ::math::statistics::pdf-pareto scale shape value
    • -
  • ::math::statistics::pdf-cauchy location scale value
    • -
  • ::math::statistics::cdf-normal mean stdev value
    • -
  • ::math::statistics::cdf-lognormal mean stdev value
    • -
  • ::math::statistics::cdf-exponential mean value
    • -
  • ::math::statistics::cdf-uniform xmin xmax value
    • -
  • ::math::statistics::cdf-students-t degrees value
    • -
  • ::math::statistics::cdf-gamma alpha beta value
    • -
  • ::math::statistics::cdf-poisson mu k
    • -
  • ::math::statistics::cdf-beta a b value
    • -
  • ::math::statistics::cdf-weibull scale shape value
    • -
  • ::math::statistics::cdf-gumbel location scale value
    • -
  • ::math::statistics::cdf-pareto scale shape value
    • -
  • ::math::statistics::cdf-cauchy location scale value
    • -
  • ::math::statistics::cdf-F nf1 nf2 value
    • -
  • ::math::statistics::empirical-distribution values
    • -
  • ::math::statistics::random-normal mean stdev number
    • -
  • ::math::statistics::random-lognormal mean stdev number
    • -
  • ::math::statistics::random-exponential mean number
    • -
  • ::math::statistics::random-uniform xmin xmax number
    • -
  • ::math::statistics::random-gamma alpha beta number
    • -
  • ::math::statistics::random-poisson mu number
    • -
  • ::math::statistics::random-chisquare df number
    • -
  • ::math::statistics::random-student-t df number
    • -
  • ::math::statistics::random-beta a b number
    • -
  • ::math::statistics::random-weibull scale shape number
    • -
  • ::math::statistics::random-gumbel location scale number
    • -
  • ::math::statistics::random-pareto scale shape number
    • -
  • ::math::statistics::random-cauchy location scale number
    • -
  • ::math::statistics::histogram-uniform xmin xmax limits number
    • -
  • ::math::statistics::incompleteGamma x p ?tol?
    • -
  • ::math::statistics::incompleteBeta a b x ?tol?
    • -
  • ::math::statistics::estimate-pareto values
    • -
  • ::math::statistics::filter varname data expression
    • -
  • ::math::statistics::map varname data expression
    • -
  • ::math::statistics::samplescount varname list expression
    • -
  • ::math::statistics::subdivide
    • -
  • ::math::statistics::plot-scale canvas xmin xmax ymin ymax
    • -
  • ::math::statistics::plot-xydata canvas xdata ydata tag
    • -
  • ::math::statistics::plot-xyline canvas xdata ydata tag
    • -
  • ::math::statistics::plot-tdata canvas tdata tag
    • -
  • ::math::statistics::plot-tline canvas tdata tag
    • -
  • ::math::statistics::plot-histogram canvas counts limits tag
    • +
  • ::math::statistics::test-Levene groups
    • +
  • ::math::statistics::test-Brown-Forsythe groups
    • +
  • ::math::statistics::group-rank args
    • +
  • ::math::statistics::test-Wilcoxon sample_a sample_b
    • +
  • ::math::statistics::spearman-rank sample_a sample_b
    • +
  • ::math::statistics::spearman-rank-extended sample_a sample_b
    • +
  • ::math::statistics::kernel-density data opt -option value ...
    • +
  • ::math::statistics::bootstrap data sampleSize ?numberSamples?
    • +
  • ::math::statistics::wasserstein-distance prob1 prob2
    • +
  • ::math::statistics::kl-divergence prob1 prob2
    • +
  • ::math::statistics::logistic-model xdata ydata
    • +
  • ::math::statistics::logistic-probability coeffs x
    • +
  • ::math::statistics::tstat dof ?alpha?
    • +
  • ::math::statistics::mv-wls wt1 weights_and_values
    • +
  • ::math::statistics::mv-ols values
    • +
  • ::math::statistics::pdf-normal mean stdev value
    • +
  • ::math::statistics::pdf-lognormal mean stdev value
    • +
  • ::math::statistics::pdf-exponential mean value
    • +
  • ::math::statistics::pdf-uniform xmin xmax value
    • +
  • ::math::statistics::pdf-triangular xmin xmax value
    • +
  • ::math::statistics::pdf-symmetric-triangular xmin xmax value
    • +
  • ::math::statistics::pdf-gamma alpha beta value
    • +
  • ::math::statistics::pdf-poisson mu k
    • +
  • ::math::statistics::pdf-chisquare df value
    • +
  • ::math::statistics::pdf-student-t df value
    • +
  • ::math::statistics::pdf-gamma a b value
    • +
  • ::math::statistics::pdf-beta a b value
    • +
  • ::math::statistics::pdf-weibull scale shape value
    • +
  • ::math::statistics::pdf-gumbel location scale value
    • +
  • ::math::statistics::pdf-pareto scale shape value
    • +
  • ::math::statistics::pdf-cauchy location scale value
    • +
  • ::math::statistics::pdf-laplace location scale value
    • +
  • ::math::statistics::pdf-kumaraswamy a b value
    • +
  • ::math::statistics::pdf-negative-binomial r p value
    • +
  • ::math::statistics::cdf-normal mean stdev value
    • +
  • ::math::statistics::cdf-lognormal mean stdev value
    • +
  • ::math::statistics::cdf-exponential mean value
    • +
  • ::math::statistics::cdf-uniform xmin xmax value
    • +
  • ::math::statistics::cdf-triangular xmin xmax value
    • +
  • ::math::statistics::cdf-symmetric-triangular xmin xmax value
    • +
  • ::math::statistics::cdf-students-t degrees value
    • +
  • ::math::statistics::cdf-gamma alpha beta value
    • +
  • ::math::statistics::cdf-poisson mu k
    • +
  • ::math::statistics::cdf-beta a b value
    • +
  • ::math::statistics::cdf-weibull scale shape value
    • +
  • ::math::statistics::cdf-gumbel location scale value
    • +
  • ::math::statistics::cdf-pareto scale shape value
    • +
  • ::math::statistics::cdf-cauchy location scale value
    • +
  • ::math::statistics::cdf-F nf1 nf2 value
    • +
  • ::math::statistics::cdf-laplace location scale value
    • +
  • ::math::statistics::cdf-kumaraswamy a b value
    • +
  • ::math::statistics::cdf-negative-binomial r p value
    • +
  • ::math::statistics::empirical-distribution values
    • +
  • ::math::statistics::random-normal mean stdev number
    • +
  • ::math::statistics::random-lognormal mean stdev number
    • +
  • ::math::statistics::random-exponential mean number
    • +
  • ::math::statistics::random-uniform xmin xmax number
    • +
  • ::math::statistics::random-triangular xmin xmax number
    • +
  • ::math::statistics::random-symmetric-triangular xmin xmax number
    • +
  • ::math::statistics::random-gamma alpha beta number
    • +
  • ::math::statistics::random-poisson mu number
    • +
  • ::math::statistics::random-chisquare df number
    • +
  • ::math::statistics::random-student-t df number
    • +
  • ::math::statistics::random-beta a b number
    • +
  • ::math::statistics::random-weibull scale shape number
    • +
  • ::math::statistics::random-gumbel location scale number
    • +
  • ::math::statistics::random-pareto scale shape number
    • +
  • ::math::statistics::random-cauchy location scale number
    • +
  • ::math::statistics::random-laplace location scale number
    • +
  • ::math::statistics::random-kumaraswamy a b number
    • +
  • ::math::statistics::random-negative-binomial r p number
    • +
  • ::math::statistics::histogram-uniform xmin xmax limits number
    • +
  • ::math::statistics::incompleteGamma x p ?tol?
    • +
  • ::math::statistics::incompleteBeta a b x ?tol?
    • +
  • ::math::statistics::estimate-pareto values
    • +
  • ::math::statistics::estimate-exponential values
    • +
  • ::math::statistics::estimate-laplace values
    • +
  • ::math::statistics::estimante-negative-binomial r values
    • +
  • ::math::statistics::filter varname data expression
    • +
  • ::math::statistics::map varname data expression
    • +
  • ::math::statistics::samplescount varname list expression
    • +
  • ::math::statistics::subdivide
    • +
  • ::math::statistics::plot-scale canvas xmin xmax ymin ymax
    • +
  • ::math::statistics::plot-xydata canvas xdata ydata tag
    • +
  • ::math::statistics::plot-xyline canvas xdata ydata tag
    • +
  • ::math::statistics::plot-tdata canvas tdata tag
    • +
  • ::math::statistics::plot-tline canvas tdata tag
    • +
  • ::math::statistics::plot-histogram canvas counts limits tag

    • Description

    The math::statistics package contains functions and procedures for @@ -696,38 +716,57 @@ equal.

    list args

    - Two or more lists of data

    -
    ::math::statistics::group-rank args
    +
    ::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
    +
    ::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.

    +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
    +
    ::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
    +
    ::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.

    @@ -734,11 +773,11 @@
    list sample_a

    - First list of data

    list sample_b

    - Second list of data

    -
    ::math::statistics::kernel-density data opt -option value ...
    +
    ::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.

    @@ -760,11 +799,11 @@
    -kernel function

    Kernel to be used (One of: gaussian, cosine, epanechnikov, uniform, triangular, biweight, logistic; default: gaussian)

    -
    ::math::statistics::bootstrap data sampleSize ?numberSamples?
    +
    ::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
    @@ -772,11 +811,11 @@
    int sampleSize

    Number of values per sample

    int numberSamples

    Number of samples (default: 1)

    -
    ::math::statistics::wasserstein-distance prob1 prob2
    +
    ::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.

    @@ -784,11 +823,11 @@
    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
    +
    ::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.

    @@ -798,21 +837,21 @@
    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
    +
    ::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
    +
    ::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

    @@ -831,11 +870,11 @@ 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?
    +
    ::math::statistics::tstat dof ?alpha?

    Returns the value of the t-distribution t* satisfying

         P(t*)  =  1 - alpha/2
     P(-t*) =  alpha/2
    @@ -855,11 +894,11 @@
    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
    +
    ::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
@@ -885,11 +924,11 @@
 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
    +
    ::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.

    @@ -950,11 +989,11 @@

  • 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
    +
    ::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

    @@ -961,11 +1000,11 @@
    float stdev

    - Standard deviation of the distribution

    float value

    - Value for which the probability is required

    -
    ::math::statistics::pdf-lognormal mean stdev value
    +
    ::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

    @@ -972,20 +1011,20 @@
    float stdev

    - Standard deviation of the distribution

    float value

    - Value for which the probability is required

    -
    ::math::statistics::pdf-exponential mean value
    +
    ::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
    +
    ::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

    @@ -992,11 +1031,35 @@
    float xmin

    - Maximum value of the distribution

    float value

    - Value for which the probability is required

    -
    ::math::statistics::pdf-gamma alpha beta value
    +
    ::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

    @@ -1003,38 +1066,38 @@
    float beta

    - Rate parameter

    float value

    - Value for which the probability is required

    -
    ::math::statistics::pdf-poisson mu k
    +
    ::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
    +
    ::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
    +
    ::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
    +
    ::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

    @@ -1041,11 +1104,11 @@
    float b

    - Rate parameter

    float value

    - Value for which the probability is required

    -
    ::math::statistics::pdf-beta a b value
    +
    ::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

    @@ -1052,11 +1115,11 @@
    float b

    - Second shape parameter

    float value

    - Value for which the probability is required

    -
    ::math::statistics::pdf-weibull scale shape value
    +
    ::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

    @@ -1063,11 +1126,11 @@
    float scale

    - Shape parameter

    float value

    - Value for which the probability is required

    -
    ::math::statistics::pdf-gumbel location scale value
    +
    ::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

    @@ -1074,11 +1137,11 @@
    float scale

    - Shape parameter

    float value

    - Value for which the probability is required

    -
    ::math::statistics::pdf-pareto scale shape value
    +
    ::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

    @@ -1085,11 +1148,11 @@
    float shape

    - Shape parameter

    float value

    - Value for which the probability is required

    -
    ::math::statistics::pdf-cauchy location scale value
    +
    ::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
    @@ -1097,11 +1160,47 @@
    float scale

    - Shape parameter

    float value

    - Value for which the probability is required

    -
    ::math::statistics::cdf-normal mean stdev value
    +
    ::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
    @@ -1109,11 +1208,11 @@
    float stdev

    - Standard deviation of the distribution

    float value

    - Value for which the probability is required

    -
    ::math::statistics::cdf-lognormal mean stdev value
    +
    ::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
    @@ -1121,20 +1220,20 @@
    float stdev

    - Standard deviation of the distribution

    float value

    - Value for which the probability is required

    -
    ::math::statistics::cdf-exponential mean value
    +
    ::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
    +
    ::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

    @@ -1141,20 +1240,43 @@
    float xmin

    - Maximum value of the distribution

    float value

    - Value for which the probability is required

    -
    ::math::statistics::cdf-students-t degrees value
    +
    ::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
    +
    ::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

    @@ -1161,20 +1283,20 @@
    float beta

    - Rate parameter

    float value

    - Value for which the cumulative probability is required

    -
    ::math::statistics::cdf-poisson mu k
    +
    ::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
    +
    ::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

    @@ -1181,11 +1303,11 @@
    float b

    - Second shape parameter

    float value

    - Value for which the probability is required

    -
    ::math::statistics::cdf-weibull scale shape value
    +
    ::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

    @@ -1192,11 +1314,11 @@
    float shape

    - Shape parameter

    float value

    - Value for which the probability is required

    -
    ::math::statistics::cdf-gumbel location scale value
    +
    ::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

    @@ -1203,11 +1325,11 @@
    float scale

    - Scale parameter

    float value

    - Value for which the probability is required

    -
    ::math::statistics::cdf-pareto scale shape value
    +
    ::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

    @@ -1214,11 +1336,11 @@
    float shape

    - Shape parameter

    float value

    - Value for which the probability is required

    -
    ::math::statistics::cdf-cauchy location scale value
    +
    ::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

    @@ -1225,11 +1347,11 @@
    float scale

    - Scale parameter

    float value

    - Value for which the probability is required

    -
    ::math::statistics::cdf-F nf1 nf2 value
    +
    ::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

    @@ -1236,18 +1358,54 @@
    float nf2

    - Degrees of freedom for the denominator

    float value

    - Value for which the probability is required

    -
    ::math::statistics::empirical-distribution values
    +
    ::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
    +
    ::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

    @@ -1254,11 +1412,11 @@
    float stdev

    - Standard deviation of the distribution

    int number

    - Number of values to be returned

    -
    ::math::statistics::random-lognormal mean stdev number
    +
    ::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

    @@ -1265,20 +1423,20 @@
    float stdev

    - Standard deviation of the distribution

    int number

    - Number of values to be returned

    -
    ::math::statistics::random-exponential mean number
    +
    ::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
    +
    ::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

    @@ -1285,11 +1443,34 @@
    float xmax

    - Maximum value of the distribution

    int number

    - Number of values to be returned

    -
    ::math::statistics::random-gamma alpha beta number
    +
    ::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

    @@ -1296,38 +1477,38 @@
    float beta

    - Rate parameter

    int number

    - Number of values to be returned

    -
    ::math::statistics::random-poisson mu number
    +
    ::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
    +
    ::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
    +
    ::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
    +
    ::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

    @@ -1334,11 +1515,11 @@
    float b

    - Second shape parameter

    int number

    - Number of values to be returned

    -
    ::math::statistics::random-weibull scale shape number
    +
    ::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

    @@ -1345,11 +1526,11 @@
    float shape

    - Shape parameter

    int number

    - Number of values to be returned

    -
    ::math::statistics::random-gumbel location scale number
    +
    ::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

    @@ -1356,11 +1537,11 @@
    float scale

    - Scale parameter

    int number

    - Number of values to be returned

    -
    ::math::statistics::random-pareto scale shape number
    +
    ::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

    @@ -1367,11 +1548,11 @@
    float shape

    - Shape parameter

    int number

    - Number of values to be returned

    -
    ::math::statistics::random-cauchy location scale number
    +
    ::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

    @@ -1378,11 +1559,46 @@
    float scale

    - Scale parameter

    int number

    - Number of values to be returned

    -
    ::math::statistics::histogram-uniform xmin xmax limits number
    +
    ::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
    @@ -1390,11 +1606,11 @@
    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?
    +
    ::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
@@ -1405,11 +1621,11 @@
 
    float p
    
 
    - Value of p in the integrand
    
 
    float tol
    
 
    - Required tolerance (default: 1.0e-9)
    -
    ::math::statistics::incompleteBeta a b x ?tol?
    +
    ::math::statistics::incompleteBeta a b x ?tol?

    Evaluate the incomplete Beta integral

    float a

    - First shape parameter

    float b
    @@ -1417,24 +1633,47 @@
    float x

    - Value of x (limit of the integral)

    float tol

    - Required tolerance (default: 1.0e-9)

    -
    ::math::statistics::estimate-pareto values
    +
    ::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
    +
    ::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

    @@ -1441,11 +1680,11 @@
    list data

    - List of data

    string expression

    - Logical expression using the variable name

    -
    ::math::statistics::map varname data expression
    +
    ::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

    @@ -1452,11 +1691,11 @@
    list data

    - List of data

    string expression

    - Expression to be used to transform (map) the data

    -
    ::math::statistics::samplescount varname list expression
    +
    ::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

    @@ -1464,18 +1703,18 @@

    - List of sublists, each containing the data

    string expression

    - Logical expression to test the data (defaults to "true").

    -
    ::math::statistics::subdivide
    +
    ::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
    +
    ::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
    @@ -1487,11 +1726,11 @@
    float ymin

    - Minimum y value

    float ymax

    - Maximum y value

    -
    ::math::statistics::plot-xydata canvas xdata ydata tag
    +
    ::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
    @@ -1501,11 +1740,11 @@
    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
    +
    ::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
    @@ -1515,11 +1754,11 @@
    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
    +
    ::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.

    @@ -1529,11 +1768,11 @@
    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
    +
    ::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

    @@ -1540,11 +1779,11 @@
    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
    +
    ::math::statistics::plot-histogram canvas counts limits tag

    Create a simple histogram in the given canvas

    widget canvas

    - Canvas widget to use

    list counts
    Index: idoc/www/tcllib/files/modules/mime/mime.html ================================================================== --- idoc/www/tcllib/files/modules/mime/mime.html +++ idoc/www/tcllib/files/modules/mime/mime.html @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
    -

    mime(n) 1.6 tcllib "Mime"

    +

    mime(n) 1.6.2 tcllib "Mime"

    Name

    mime - Manipulation of MIME body parts

    Table Of Contents

      @@ -126,11 +126,11 @@

    Synopsis

    • package require Tcl 8.5
      • -
    • package require mime ?1.6?
      • +
    • package require mime ?1.6.2?
    ::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.

    +

    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.

    +

    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 Index: idoc/www/tcllib/files/modules/pop3/pop3.html ================================================================== --- idoc/www/tcllib/files/modules/pop3/pop3.html +++ idoc/www/tcllib/files/modules/pop3/pop3.html @@ -312,11 +312,11 @@ 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 \\
+	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 @@ -325,11 +325,11 @@ proceeding with authentication.

     	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
 	...

    Bugs, Ideas, Feedback

    Index: idoc/www/tcllib/files/modules/pop3d/pop3d.html ================================================================== --- idoc/www/tcllib/files/modules/pop3d/pop3d.html +++ idoc/www/tcllib/files/modules/pop3d/pop3d.html @@ -307,11 +307,11 @@ 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 \\
+	tls::init \
 		...
 	pop3d::new S -socket tls::socket
 	...
    Index: idoc/www/tcllib/files/modules/practcl/practcl.html ================================================================== --- idoc/www/tcllib/files/modules/practcl/practcl.html +++ idoc/www/tcllib/files/modules/practcl/practcl.html @@ -105,78 +105,1462 @@ | Categories | Modules | Applications ]
    -

    practcl(n) 0.11 tcllib "The The Proper Rational API for C to Tool Command Language Module"

    +

    practcl(n) 0.16.4 tcllib "The The Proper Rational API for C to Tool Command Language Module"

    Name

    practcl - The Practcl Module

    Synopsis

    • package require TclOO 1.0
      • -
    • package require practcl 0.11

    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

    +

    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 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.

    +

    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 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 ?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::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.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
    +
    +
    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 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
    +
    +
    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.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. Please also report any ideas for enhancements you may have for either Index: idoc/www/tcllib/files/modules/profiler/profiler.html ================================================================== --- idoc/www/tcllib/files/modules/profiler/profiler.html +++ idoc/www/tcllib/files/modules/profiler/profiler.html @@ -103,11 +103,11 @@ | Categories | Modules | Applications ]

    -

    profiler(n) 0.3 tcllib "Tcl Profiler"

    +

    profiler(n) 0.5 tcllib "Tcl Profiler"

    Name

    profiler - Tcl source code profiler

    Table Of Contents

      @@ -122,20 +122,22 @@

    Description

    The profiler package provides a simple Tcl source code @@ -195,11 +197,21 @@

    ::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
    +
    ::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 Index: idoc/www/tcllib/files/modules/pt/pt_peg_export.html ================================================================== --- idoc/www/tcllib/files/modules/pt/pt_peg_export.html +++ idoc/www/tcllib/files/modules/pt/pt_peg_export.html @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]

    -

    pt::peg::export(n) 1 tcllib "Parser Tools"

    +

    pt::peg::export(n) 1.0.1 tcllib "Parser Tools"

    Name

    pt::peg::export - PEG Export

    Table Of Contents

    -
    ::simulation::random::prng_Exponential min mean
    +
    ::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
    +
    ::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
    +
    ::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
    +
    ::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)))
@@ -237,11 +259,11 @@
 
    float min
    
 
    Minimum number that will be generated
    
 
    float f
    
 
    Scale factor for the values
    -
    ::simulation::random::prng_chiSquared df
    +
    ::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
    @@ -248,41 +270,41 @@

    Degrees of freedom

    The package defines the following public procedures for random point sets:

    -
    ::simulation::random::prng_Disk rad
    +
    ::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
    +
    ::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
    +
    ::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
    +
    ::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
    +
    ::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)

    Index: idoc/www/tcllib/files/modules/struct/graph.html ================================================================== --- idoc/www/tcllib/files/modules/struct/graph.html +++ idoc/www/tcllib/files/modules/struct/graph.html @@ -91,11 +91,11 @@ } --> -
    [ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
    -

    struct::graph(n) 2.4.1 tcllib "Tcl Data Structures"

    +

    struct::graph(n) 2.4.3 tcllib "Tcl Data Structures"

    Name

    struct::graph - Create and manipulate directed graph objects

    Table Of Contents

      @@ -125,11 +125,11 @@

    Synopsis

    • package require Tcl 8.4
      • -
    • package require struct::graph ?2.4.1?
      • +
    • 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?
      • @@ -429,11 +429,11 @@ 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 +-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.

      @@ -460,10 +460,18 @@ 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 @@ -563,13 +571,16 @@

    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:

    +

    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 @@ -673,14 +684,14 @@ relevance, nor has the order of the arcs per node.

         # A possible serialization for the graph structure
     #
     #        d -----> %2
-    #       /         ^ \\
-    #      /         /   \\
-    #     /         b     \\
-    #    /         /       \\
+    #       /         ^ \
+    #      /         /   \
+    #     /         b     \
+    #    /         /       \
     #  %1 <- a - %0         e
     #    ^         \\      /
     #     \\        c     /
     #      \\        \\  /
     #       \\        v v
@@ -786,8 +797,8 @@

    Category

    Data structures

    Index: idoc/www/tcllib/files/modules/struct/matrix.html ================================================================== --- idoc/www/tcllib/files/modules/struct/matrix.html +++ idoc/www/tcllib/files/modules/struct/matrix.html @@ -91,11 +91,11 @@ } --> -
    [ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
    -

    struct::matrix(n) 2.0.3 tcllib "Tcl Data Structures"

    +

    struct::matrix(n) 2.0.4 tcllib "Tcl Data Structures"

    Name

    struct::matrix - Create and manipulate matrix objects

    Table Of Contents

      @@ -125,11 +125,11 @@

    Synopsis

    • package require Tcl 8.2
      • -
    • package require struct::matrix ?2.0.3?
      • +
    • package require struct::matrix ?2.0.4?

    Category

    Data structures

    Index: idoc/www/tcllib/files/modules/struct/matrix1.html ================================================================== --- idoc/www/tcllib/files/modules/struct/matrix1.html +++ idoc/www/tcllib/files/modules/struct/matrix1.html @@ -91,11 +91,11 @@ } --> -
    [ Tcllib Home @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
    -

    struct::matrix_v1(n) 1.2.1 tcllib "Tcl Data Structures"

    +

    struct::matrix_v1(n) 1.2.2 tcllib "Tcl Data Structures"

    Name

    struct::matrix_v1 - Create and manipulate matrix objects

    Table Of Contents

      @@ -125,11 +125,11 @@

    Synopsis

    • package require Tcl 8.2
      • -
    • package require struct::matrix ?1.2.1?
      • +
    • package require struct::matrix ?1.2.2?

    Category

    Data structures

    Index: idoc/www/tcllib/files/modules/struct/record.html ================================================================== --- idoc/www/tcllib/files/modules/struct/record.html +++ idoc/www/tcllib/files/modules/struct/record.html @@ -105,23 +105,34 @@ | Categories | Modules | Applications ]
    -

    struct::record(n) 1.2.1 tcllib "Tcl Data Structures"

    +

    struct::record(n) 1.2.2 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.

    +

    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 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. 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.

    +

    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.

    +

    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.

    @@ -186,23 +207,25 @@ 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.

    +

    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.

    +

    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. For example, it would look like this:

    +nested record (within the container). For example, it would look like +this:

     # this is the nested record
 record define mynestedrecord {
     nest1
     nest2
@@ -212,127 +235,153 @@
     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:

    +

    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

    +

    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.

    -
      -

    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

    +
    +
    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.

    -
      -

    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:

    +
    +
    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 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
+% # Create an instance first
 % myrecord inst1
 ::inst1
-% # To get a member of an instance, just use the
-% # alias (it behaves like a Tcl command):
+% # 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)
+% # 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)
+% # 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
+% # 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:

    +

    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.

    +
    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 +recordNameN, 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 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.

    +
    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 an good illustration on how to use +

    Two examples are provided to give a 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:

    +

    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.
+##  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
@@ -378,41 +427,43 @@
 first middle last {record locations home} {record locations work}
 % record show members contacts
 first middle last {record locations home} {record locations work}
 %
    -

    Example 1

    +
    +

    Example 2 - Linked List

    This next example just illustrates a simple linked list

     % # define a very simple record for linked list
-% record define llist {
+% record define linkedlist {
     value
     next
 }
-::llist
-% llist lstart
+::linkedlist
+% linkedlist lstart
 ::lstart
-% lstart config -value 1 -next [llist #auto]
-% [lstart cget -next] config -value 2 -next [llist #auto]
+% 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}
+    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
+% # We could just use delete record linkedlist also
+% foreach I [record show instances linkedlist] {
+    record delete instance $I
 }
-% record show instances llist
+% 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 ADDED idoc/www/tcllib/files/modules/struct/struct_map.html Index: idoc/www/tcllib/files/modules/struct/struct_map.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/modules/struct/struct_map.html @@ -0,0 +1,190 @@ + +struct::map - + + + + +

    [ + Tcllib Home +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
    +
    +

    struct::map(n) 1 tcllib ""

    +

    Name

    +

    struct::map - Manage key/value maps

    +
    + + +

    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 arguments 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 patterns 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. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

    +

    When proposing code changes, please provide unified diffs, +i.e the output of diff -u.

    +

    Note further that attachments are strongly preferred over +inlined patches. Attachments can be made by going to the Edit +form of the ticket immediately after its creation, and then using the +left-most button in the secondary navigation bar.

    +
    +
    ADDED idoc/www/tcllib/files/modules/textutil/patch.html Index: idoc/www/tcllib/files/modules/textutil/patch.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/modules/textutil/patch.html @@ -0,0 +1,188 @@ + +textutil::patch - Text and string utilities + + + + +
    [ + Tcllib Home +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
    +
    +

    textutil::patch(n) 0.1 tcllib "Text and string utilities"

    +

    Name

    +

    textutil::patch - Application of uni-diff patches to directory trees

    +
    + + +

    Description

    +

    This package provides a single command which applies a patch in +unified format +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 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. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

    +

    When proposing code changes, please provide unified diffs, +i.e the output of diff -u.

    +

    Note further that attachments are strongly preferred over +inlined patches. Attachments can be made by 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/treeql/treeql.html ================================================================== --- idoc/www/tcllib/files/modules/treeql/treeql.html +++ idoc/www/tcllib/files/modules/treeql/treeql.html @@ -252,13 +252,13 @@ # 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 \\ + 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.

    Index: idoc/www/tcllib/files/modules/virtchannel_base/cat.html ================================================================== --- idoc/www/tcllib/files/modules/virtchannel_base/cat.html +++ idoc/www/tcllib/files/modules/virtchannel_base/cat.html @@ -105,11 +105,11 @@ | Categories | Modules | Applications ]
    -

    tcl::chan::cat(n) 1 tcllib "Reflected/virtual channel support"

    +

    tcl::chan::cat(n) 1.0.3 tcllib "Reflected/virtual channel support"

    Name

    tcl::chan::cat - Concatenation channel

    Table Of Contents