$f	$v

$field

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

is either 'y' or 'n' + indicating whether posting to this newsgroup is allowed ('y') or prohibited + ('n'). + + - *nntpName* __newnews__ + + Query the server for a list of new articles posted to the current group in + the last day. + + - *nntpName* __newnews__ *since* + + Query the server for a list of new articles posted to the current group + since the time specified by the argument *since*. The argument *since* can + be any time string that is understood by __clock scan__. + + - *nntpName* __newnews__ *group* ?*since*? + + Query the server for a list of new articles posted to the group specified by + the argument *group* since the time specified by the argument *since* (or in + the past day if no *since* argument is passed. The argument *since* can be + any time string that is understood by __clock scan__. + + - *nntpName* __next__ + + Sets the current article pointer to point to the next message (if there is + one) and returns the msgid of that message. + + - *nntpName* __post__ *article* + + Posts an article of the form specified in RFC 1036 + ([http://www.rfc-editor.org/rfc/rfc1036.txt](http://www.rfc-editor.org/rfc/rfc1036.txt), + successor to RFC 850) to the current news group. + + - *nntpName* __slave__ + + Identifies a connection as being made from a slave nntp server. This might + be used to indicate that the connection is serving multiple people and + should be given priority. Actual use is entirely implementation dependent + and may vary from server to server. + + - *nntpName* __stat__ ?*msgid*? + + The stat command is similar to the article command except that no text is + returned. When selecting by message number within a group, the stat command + serves to set the current article pointer without sending text. The returned + acknowledgment response will contain the message-id, which may be of some + value. Using the stat command to select by message-id is valid but of + questionable value, since a selection by message-id does NOT alter the + "current article pointer" + + - *nntpName* __quit__ + + Gracefully close the connection after sending a NNTP QUIT command down the + socket. + + - *nntpName* __xgtitle__ ?*group_pattern*? + + Returns a tcl list where each element is of the form: + + newsgroup description + + If a *group_pattern* is specified then only newsgroups that match the + pattern will have their name and description returned. + + - *nntpName* __xhdr__ *field* ?*range*? + + Returns the specified header field value for the current message or for a + list of messages from the current group. *field* is the title of a field in + the header such as from, subject, date, etc. If *range* is not specified or + is "" then the current message is queried. The command returns a list of + elements where each element has the form of: + + msgid value + + Where msgid is the number of the message and value is the value set for the + queried field. The *range* argument can be in any of the following forms: + + * __""__ + + The current message is queried. + + * *msgid1*-*msgid2* + + All messages between *msgid1* and *msgid2* (including *msgid1* and + *msgid2*) are queried. + + * *msgid1* *msgid2* + + All messages between *msgid1* and *msgid2* (including *msgid1* and + *msgid2*) are queried. + + - *nntpName* __xover__ ?*range*? + + Returns header information for the current message or for a range of + messages from the current group. The information is returned in a tcl list + where each element is of the form: + + msgid subject from date idstring bodysize headersize xref + + If *range* is not specified or is "" then the current message is queried. + The *range* argument can be in any of the following forms: + + * __""__ + + The current message is queried. + + * *msgid1*-*msgid2* + + All messages between *msgid1* and *msgid2* (including *msgid1* and + *msgid2*) are queried. + + * *msgid1* *msgid2* + + All messages between *msgid1* and *msgid2* (including *msgid1* and + *msgid2*) are queried. + + - *nntpName* __xpat__ *field* *range* ?*pattern_list*? + + Returns the specified header field value for a specified message or for a + list of messages from the current group where the messages match the + pattern(s) given in the pattern_list. *field* is the title of a field in the + header such as from, subject, date, etc. The information is returned in a + tcl list where each element is of the form: + + msgid value + + Where msgid is the number of the message and value is the value set for the + queried field. The *range* argument can be in any of the following forms: + + * *msgid* + + The message specified by *msgid* is queried. + + * *msgid1*-*msgid2* + + All messages between *msgid1* and *msgid2* (including *msgid1* and + *msgid2*) are queried. + + * *msgid1* *msgid2* + + All messages between *msgid1* and *msgid2* (including *msgid1* and + *msgid2*) are queried. + +# EXAMPLE + +A bigger example for posting a single article. + + package require nntp + set n [nntp::nntp NNTP_SERVER] + $n post "From: USER@DOMAIN.EXT (USER_FULL) + Path: COMPUTERNAME!USERNAME + Newsgroups: alt.test + Subject: Tcl test post -ignore + Message-ID: <[pid][clock seconds] + @COMPUTERNAME> + Date: [clock format [clock seconds] -format "%a, %d % + b %y %H:%M:%S GMT" -gmt true] + + Test message body" + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *nntp* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[news](../../../../index.md#news), [nntp](../../../../index.md#nntp), +[nntpclient](../../../../index.md#nntpclient), [rfc +1036](../../../../index.md#rfc_1036), [rfc 977](../../../../index.md#rfc_977) + +# CATEGORY + +Networking ADDED embedded/md/tcllib/files/modules/ntp/ntp_time.md Index: embedded/md/tcllib/files/modules/ntp/ntp_time.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/ntp/ntp_time.md @@ -0,0 +1,194 @@ + +[//000000001]: # (ntp_time - Network Time Facilities) +[//000000002]: # (Generated from file 'ntp_time.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (ntp_time(n) 1.2.1 tcllib "Network Time Facilities") + +# NAME + +ntp_time - Tcl Time Service Client + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [AUTHORS](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.0 +package require time ?1.2.1? + +[__::time::gettime__ ?*options*? *timeserver* ?*port*?](#1) +[__::time::getsntp__ ?*options*? *timeserver* ?*port*?](#2) +[__::time::configure__ ?*options*?](#3) +[__::time::cget__ *name*](#4) +[__::time::unixtime__ *token*](#5) +[__::time::status__ *token*](#6) +[__::time::error__ *token*](#7) +[__::time::reset__ *token* *?reason?*](#8) +[__::time::wait__ *token*](#9) +[__::time::cleanup__ *token*](#10) + +# DESCRIPTION + +This package implements a client for the RFC 868 TIME protocol +([http://www.rfc-editor.org/rfc/rfc868.txt](http://www.rfc-editor.org/rfc/rfc868.txt)) +and also a minimal client for the RFC 2030 Simple Network Time Protocol +([http://www.rfc-editor.org/rfc/rfc2030.txt](http://www.rfc-editor.org/rfc/rfc2030.txt)). +RFC 868 returns the time in seconds since 1 January 1900 to either tcp or udp +clients. RFC 2030 also gives this time but also provides a fractional part which +is not used in this client. + +# COMMANDS + + - __::time::gettime__ ?*options*? *timeserver* ?*port*? + + Get the time from *timeserver*. You may specify any of the options listed + for the __configure__ command here. This command returns a token which must + then be used with the remaining commands in this package. Once you have + finished, you should use __[cleanup](../../../../index.md#cleanup)__ to + release all resources. The default port is __37__. + + - __::time::getsntp__ ?*options*? *timeserver* ?*port*? + + Get the time from an SNTP server. This accepts exactly the same arguments as + __::time::gettime__ except that the default port is __123__. The result is a + token as per __::time::gettime__ and should be handled in the same way. + + Note that it is unlikely that any SNTP server will reply using tcp so you + will require the __tcludp__ or the __ceptcl__ package. If a suitable package + can be loaded then the udp protocol will be used by default. + + - __::time::configure__ ?*options*? + + Called with no arguments this command returns all the current configuration + options and values. Otherwise it should be called with pairs of option name + and value. + + * __-protocol__ *number* + + Set the default network protocol. This defaults to udp if the tcludp + package is available. Otherwise it will use tcp. + + * __-port__ *number* + + Set the default port to use. RFC 868 uses port __37__, RFC 2030 uses + port __123__. + + * __-timeout__ *number* + + Set the default timeout value in milliseconds. The default is 10 + seconds. + + * __-command__ *number* + + Set a command procedure to be run when a reply is received. The + procedure is called with the time token appended to the argument list. + + * __-loglevel__ *number* + + Set the logging level. The default is 'warning'. + + - __::time::cget__ *name* + + Get the current value for the named configuration option. + + - __::time::unixtime__ *token* + + Format the returned time for the unix epoch. RFC 868 time defines time 0 as + 1 Jan 1900, while unix time defines time 0 as 1 Jan 1970. This command + converts the reply to unix time. + + - __::time::status__ *token* + + Returns the status flag. For a successfully completed query this will be + *ok*. May be *error* or *timeout* or *eof*. See also __::time::error__ + + - __::time::error__ *token* + + Returns the error message provided for requests whose status is *error*. If + there is no error message then an empty string is returned. + + - __::time::reset__ *token* *?reason?* + + Reset or cancel the query optionally specfying the reason to record for the + __[error](../../../../index.md#error)__ command. + + - __::time::wait__ *token* + + Wait for a query to complete and return the status upon completion. + + - __::time::cleanup__ *token* + + Remove all state variables associated with the request. + + % set tok [::time::gettime ntp2a.mcc.ac.uk] + % set t [::time::unixtime $tok] + % ::time::cleanup $tok + + % set tok [::time::getsntp pool.ntp.org] + % set t [::time::unixtime $tok] + % ::time::cleanup $tok + + proc on_time {token} { + if {[time::status $token] eq "ok"} { + puts [clock format [time::unixtime $token]] + } else { + puts [time::error $token] + } + time::cleanup $token + } + time::getsntp -command on_time pool.ntp.org + +# AUTHORS + +Pat Thoyts + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *ntp* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +ntp + +# KEYWORDS + +[NTP](../../../../index.md#ntp), [SNTP](../../../../index.md#sntp), [rfc +2030](../../../../index.md#rfc_2030), [rfc 868](../../../../index.md#rfc_868), +[time](../../../../index.md#time) + +# CATEGORY + +Networking + +# COPYRIGHT + +Copyright © 2002, Pat Thoyts ADDED embedded/md/tcllib/files/modules/oauth/oauth.md Index: embedded/md/tcllib/files/modules/oauth/oauth.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/oauth/oauth.md @@ -0,0 +1,255 @@ + +[//000000001]: # (oauth - oauth) +[//000000002]: # (Generated from file 'oauth.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (oauth(n) 1.0.2 tcllib "oauth") + +# NAME + +oauth - oauth API base signature + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [TLS Security Considerations](#section2) + + - [Commands](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require oauth ?1.0.2? + +[__::oauth::config__](#1) +[__::oauth::config__ ?*options*...?](#2) +[__::oauth::header__ *baseURL* ?*postQuery*?](#3) +[__::oauth::query__ *baseURL* ?*postQuery*?](#4) + +# DESCRIPTION + +The __oauth__ package provides a simple Tcl-only library for communication with +[oauth](http://oauth.net) APIs. This current version of the package supports the +Oauth 1.0 Protocol, as specified in [RFC +5849](http://tools.ietf.org/rfc/rfc5849.txt). + +# TLS Security Considerations + +This package uses the __[TLS](../../../../index.md#tls)__ package to handle the +security for __https__ urls and other socket connections. + +Policy decisions like the set of protocols to support and what ciphers to use +are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this +package itself however. Such decisions are the responsibility of whichever +application is using the package, and are likely influenced by the set of +servers the application will talk to as well. + +For example, in light of the recent [POODLE +attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html) +discovered by Google many servers will disable support for the SSLv3 protocol. +To handle this change the applications using __[TLS](../../../../index.md#tls)__ +must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__ +itself. Such a patch may be as simple as generally activating __tls1__ support, +as shown in the example below. + + package require tls + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol + + ... your own application code ... + +# Commands + + - __::oauth::config__ + + When this command is invoked without arguments it returns a dictionary + containing the current values of all options. + + - __::oauth::config__ ?*options*...? + + When invoked with arguments, options followed by their values, it is used to + set and query various parameters of application and client, like proxy host + and user agent for the HTTP requests. The detailed list of options is below: + + * __-accesstoken__ *string* + + This is the user's token. + + * __-accesstokensecret__ *string* + + This is the user's secret token. + + * __-consumerkey__ *string* + + This is the public token of your app. + + * __-consumersecret__ *string* + + This is the private token of your app. + + * __-debug__ *bool* + + The default value is __off__. If you change this option to __on__, the + basic signature just created will be printed to stdout, among other + debug output. + + * __-oauthversion__ *version* + + This is the version of the OAuth protocol to use. At the moment only + __1.0__ is supported, the default. + + * __-proxyhost__ *hostname* + + You can set up a proxy host for send contact the oauth's api server. + + * __-proxyport__ *port-number* + + Port number of your proxy. + + * __-signmethod__ *method* + + The signature method to use. OAuth 1.0 only supports __HMAC-SHA1__, the + default. + + * __-timeout__ *milliseconds* + + Timeout in milliseconds for your query. The default value is __6000__, + i.e. 6 seconds. + + * __-urlencoding__ *encoding* + + The encoding used for creating the x-url-encoded URLs with + __::http::formatQuery__. The default is __utf-8__, as specified by [RFC + 2718](http://tools.ietf.org/rfc/rfc2718.txt). + + - __::oauth::header__ *baseURL* ?*postQuery*? + + This command is the base signature creator. With proper settings for various + tokens and secrets (See __::oauth::config__) the result is the base + authentication string to send to the server. + + You do not need to call this procedure to create the query because + __::oauth::query__ (see below) will do for it for you. Doing so is useful + for debugging purposes, though. + + * url *baseURL* + + This argument is the URI path to the OAuth API server. If you plan send + a GET query, you should provide a full path. + + HTTP GET + ::oauth::header {https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente} + + * url-encoded-string *postQuery* + + When you have to send a header in POST format, you have to put the query + string into this argument. + + ::oauth::header {https://api.twitter.com/1.1/friendships/create.json} {user_id=158812437&follow=true} + + - __::oauth::query__ *baseURL* ?*postQuery*? + + This procedure will use the settings made with __::oauth::config__ to create + the basic authentication and then send the command to the server API. It + takes the same arguments as __::oauth::header__. + + The returned result will be a list containing 2 elements. The first element + will be a dictionary containing the HTTP header data response. This allows + you, for example, to check the X-Rate-Limit from OAuth. The second element + will be the raw data returned from API server. This string is usually a json + object which can be further decoded with the functions of package + __[json](../json/json.md)__, or any other json-parser for Tcl. + + Here is an example of how it would work in Twitter. Do not forget to replace + the placeholder tokens and keys of the example with your own tokens and keys + when trying it out. + + % package require oauth + % package require json + % oauth::config -consumerkey {your_consumer_key} -consumersecret {your_consumer_key_secret} -accesstoken {your_access_token} -accesstokensecret {your_access_token_secret} + + % set response [oauth::query https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente] + % set jsondata [lindex $response 1] + % set data [json::json2dict $jsondata] + $ set data [lindex $data 0] + % dict for {key val} $data {puts "$key => $val"} + id => 158812437 + id_str => 158812437 + name => Un Librepensador + screen_name => AbiertaMente + location => Explico mis tuits ahí → + description => 160Caracteres para un SMS y contaba mi vida entera sin recortar vocales. Ahora en Twitter, podemos usar hasta 140 y a mí me sobrarían 20 para contaros todo lo q + url => http://t.co/SGs3k9odBn + entities => url {urls {{url http://t.co/SGs3k9odBn expanded_url http://librepensamiento.es display_url librepensamiento.es indices {0 22}}}} description {urls {}} + protected => false + followers_count => 72705 + friends_count => 53099 + listed_count => 258 + created_at => Wed Jun 23 18:29:58 +0000 2010 + favourites_count => 297 + utc_offset => 7200 + time_zone => Madrid + geo_enabled => false + verified => false + statuses_count => 8996 + lang => es + status => created_at {Sun Oct 12 08:02:38 +0000 2014} id 521209314087018496 id_str 521209314087018496 text {@thesamethanhim http://t.co/WFoXOAofCt} source {Twitter Web Client} truncated false in_reply_to_status_id 521076457490350081 in_reply_to_status_id_str 521076457490350081 in_reply_to_user_id 2282730867 in_reply_to_user_id_str 2282730867 in_reply_to_screen_name thesamethanhim geo null coordinates null place null contributors null retweet_count 0 favorite_count 0 entities {hashtags {} symbols {} urls {{url http://t.co/WFoXOAofCt expanded_url http://www.elmundo.es/internacional/2014/03/05/53173dc1268e3e3f238b458a.html display_url elmundo.es/internacional/… indices {16 38}}} user_mentions {{screen_name thesamethanhim name Ἑλένη id 2282730867 id_str 2282730867 indices {0 15}}}} favorited false retweeted false possibly_sensitive false lang und + contributors_enabled => false + is_translator => true + is_translation_enabled => false + profile_background_color => 709397 + profile_background_image_url => http://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg + profile_background_image_url_https => https://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg + profile_background_tile => true + profile_image_url => http://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg + profile_image_url_https => https://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg + profile_banner_url => https://pbs.twimg.com/profile_banners/158812437/1400828874 + profile_link_color => FF3300 + profile_sidebar_border_color => FFFFFF + profile_sidebar_fill_color => A0C5C7 + profile_text_color => 333333 + profile_use_background_image => true + default_profile => false + default_profile_image => false + following => true + follow_request_sent => false + notifications => false + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *oauth* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[RFC 2718](../../../../index.md#rfc_2718), [RFC +5849](../../../../index.md#rfc_5849), [oauth](../../../../index.md#oauth), +[twitter](../../../../index.md#twitter) + +# CATEGORY + +Networking + +# COPYRIGHT + +Copyright © 2014 Javi P. ADDED embedded/md/tcllib/files/modules/oometa/oometa.md Index: embedded/md/tcllib/files/modules/oometa/oometa.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/oometa/oometa.md @@ -0,0 +1,205 @@ + +[//000000001]: # (oometa - Data registry for TclOO frameworks) +[//000000002]: # (Generated from file 'oometa.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (oometa(n) 0.7.1 tcllib "Data registry for TclOO frameworks") + +# NAME + +oometa - oo::meta A data registry for classess + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Usage](#section2) + + - [Concept](#section3) + + - [COMMANDS](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +[__oo::meta::info__](#1) +[__oo::meta::info branchget__ ?*key*? ?...?](#2) +[__oo::meta::info branchset__ ?*key...*? *key* *value*](#3) +[__oo::meta::info dump__ *class*](#4) +[__oo::meta::info__ *class* __is__ *type* ?*args*?](#5) +[__oo::meta::info__ *class* __[merge](../../../../index.md#merge)__ ?*dict*? ?*dict*? ?*...*?](#6) +[__oo::meta::info__ *class* __rebuild__](#7) +[__oo::meta::metadata__ *class*](#8) +[__oo::define meta__](#9) +[__oo::class method meta__](#10) +[__oo::object method meta__](#11) +[__oo::object method meta cget__ ?*field*? ?*...*? *field*](#12) + +# DESCRIPTION + +The __oo::meta__ package provides a data registry service for TclOO classes. + +# Usage + + oo::class create animal { + meta set biodata animal: 1 + } + oo::class create mammal { + superclass animal + meta set biodata mammal: 1 + } + oo::class create cat { + superclass mammal + meta set biodata diet: carnivore + } + + cat create felix + puts [felix meta dump biodata] + > animal: 1 mammal: 1 diet: carnivore + + felix meta set biodata likes: {birds mice} + puts [felix meta get biodata] + > animal: 1 mammal: 1 diet: carnivore likes: {bird mice} + + # Modify a class + mammal meta set biodata metabolism: warm-blooded + puts [felix meta get biodata] + > animal: 1 mammal: 1 metabolism: warm-blooded diet: carnivore likes: {birds mice} + + # Overwrite class info + felix meta set biodata mammal: yes + puts [felix meta get biodata] + > animal: 1 mammal: yes metabolism: warm-blooded diet: carnivore likes: {birds mice} + +# Concept + +The concept behind __oo::meta__ is that each class contributes a snippet of +*local* data. When __oo::meta::metadata__ is called, the system walks through +the linear ancestry produced by __oo::meta::ancestors__, and recursively +combines all of that local data for all of a class' ancestors into a single +dict. Instances of oo::object can also combine class data with a local dict +stored in the *meta* variable. + +# COMMANDS + + - __oo::meta::info__ + + __oo::meta::info__ is intended to work on the metadata of a class in a + manner similar to if the aggregate pieces where assembled into a single + dict. The system mimics all of the standard dict commands, and addes the + following: + + - __oo::meta::info branchget__ ?*key*? ?...? + + Returns a dict representation of the element at *args*, but with any + trailing : removed from field names. + + ::oo::meta::info $myclass set option color {default: green widget: colorselect} + puts [::oo::meta::info $myclass get option color] + > {default: green widget: color} + puts [::oo::meta::info $myclass branchget option color] + > {default green widget color} + + - __oo::meta::info branchset__ ?*key...*? *key* *value* + + Merges *dict* with any other information contaned at node ?*key...*?, and + adding a trailing : to all field names. + + ::oo::meta::info $myclass branchset option color {default green widget colorselect} + puts [::oo::meta::info $myclass get option color] + > {default: green widget: color} + + - __oo::meta::info dump__ *class* + + Returns the complete snapshot of a class metadata, as producted by + __oo::meta::metadata__ + + - __oo::meta::info__ *class* __is__ *type* ?*args*? + + Returns a boolean true or false if the element ?*args*? would match __string + is__ *type* *value* + + ::oo::meta::info $myclass set constant mammal 1 + puts [::oo::meta::info $myclass is true constant mammal] + > 1 + + - __oo::meta::info__ *class* __[merge](../../../../index.md#merge)__ ?*dict*? ?*dict*? ?*...*? + + Combines all of the arguments into a single dict, which is then stored as + the new local representation for this class. + + - __oo::meta::info__ *class* __rebuild__ + + Forces the meta system to destroy any cached representation of a class' + metadata before the next access to __oo::meta::metadata__ + + - __oo::meta::metadata__ *class* + + Returns an aggregate picture of the metadata for *class*, combining its + *local* data with the *local* data from its ancestors. + + - __oo::define meta__ + + The package injects a command __oo::define::meta__ which works to provide a + class in the process of definition access to __oo::meta::info__, but without + having to look the name up. + + oo::define myclass { + meta set foo bar: baz + } + + - __oo::class method meta__ + + The package injects a new method __meta__ into __oo::class__ which works to + provide a class instance access to __oo::meta::info__. + + - __oo::object method meta__ + + The package injects a new method __meta__ into __oo::object__. + __oo::object__ combines the data for its class (as provided by + __oo::meta::metadata__), with a local variable *meta* to produce a local + picture of metadata. This method provides the following additional commands: + + - __oo::object method meta cget__ ?*field*? ?*...*? *field* + + Attempts to locate a singlar leaf, and return its value. For single option + lookups, this is faster than __my meta getnull__ ?*field*? ?*...*? *field*], + because it performs a search instead directly instead of producing the + recursive merge product between the class metadata, the local *meta* + variable, and THEN performing the search. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *tcloo* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[TOOL](../../../../index.md#tool), [TclOO](../../../../index.md#tcloo) + +# CATEGORY + +TclOO + +# COPYRIGHT + +Copyright © 2015 Sean Woods ADDED embedded/md/tcllib/files/modules/ooutil/ooutil.md Index: embedded/md/tcllib/files/modules/ooutil/ooutil.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/ooutil/ooutil.md @@ -0,0 +1,209 @@ + +[//000000001]: # (oo::util - Utility commands for TclOO) +[//000000002]: # (Generated from file 'ooutil.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (oo::util(n) 1.2.2 tcllib "Utility commands for TclOO") + +# NAME + +oo::util - Utility commands for TclOO + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [AUTHORS](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require oo::util ?1.2.2? + +[__mymethod__ *method* ?*arg*...?](#1) +[__classmethod__ *name* *arguments* *body*](#2) +[__classvariable__ ?*arg*...?](#3) +[__link__ *method*...](#4) +[__link__ {*alias* *method*}...](#5) +[__ooutil::singleton__ ?*arg*...?](#6) + +# DESCRIPTION + +This package provides a convenience command for the easy specification of +instance methods as callback commands, like timers, file events, Tk bindings, +etc. + +# COMMANDS + + - __mymethod__ *method* ?*arg*...? + + This command is available within instance methods. It takes a method name + and, possibly, arguments for the method and returns a command prefix which, + when executed, will invoke the named method of the object we are in, with + the provided arguments, and any others supplied at the time of actual + invokation. + + Note: The command is equivalent to and named after the command provided by + the OO package __[snit](../snit/snit.md)__ for the same purpose. + + - __classmethod__ *name* *arguments* *body* + + This command is available within class definitions. It takes a method name + and, possibly, arguments for the method and creates a method on the class, + available to a user of the class and of derived classes. + + Note: The command is equivalent to the command __typemethod__ provided by + the OO package __[snit](../snit/snit.md)__ for the same purpose. + + Example + + oo::class create ActiveRecord { + classmethod find args { puts "[self] called with arguments: $args" } + } + oo::class create Table { + superclass ActiveRecord + } + puts [Table find foo bar] + # ====== + # which will write + # ====== + # ::Table called with arguments: foo bar + + - __classvariable__ ?*arg*...? + + This command is available within instance methods. It takes a series of + variable names and makes them available in the method's scope. The + originating scope for the variables is the class (instance) the object + instance belongs to. In other words, the referenced variables are shared + between all instances of their class. + + Note: The command is roughly equivalent to the command __typevariable__ + provided by the OO package __[snit](../snit/snit.md)__ for the same purpose. + The difference is that it cannot be used in the class definition itself. + + Example: + + % oo::class create Foo { + method bar {z} { + classvariable x y + return [incr x $z],[incr y] + } + } + ::Foo + % Foo create a + ::a + % Foo create b + ::b + % a bar 2 + 2,1 + % a bar 3 + 5,2 + % b bar 7 + 12,3 + % b bar -1 + 11,4 + % a bar 0 + 11,5 + + - __link__ *method*... + + - __link__ {*alias* *method*}... + + This command is available within instance methods. It takes a list of method + names and/or pairs of alias- and method-name and makes the named methods + available to all instance methods without requiring the __my__ command. + + The alias name under which the method becomes available defaults to the + method name, except where explicitly specified through an alias/method pair. + + Examples: + + link foo + # The method foo is now directly accessible as foo instead of my foo. + + link {bar foo} + # The method foo is now directly accessible as bar. + + link a b c + # The methods a, b, and c all become directly acessible under their + # own names. + + The main use of this command is expected to be in instance constructors, for + convenience, or to set up some methods for use in a mini DSL. + + - __ooutil::singleton__ ?*arg*...? + + This command is a meta-class, i.e. a variant of the builtin __oo::class__ + which ensures that it creates only a single instance of the classes defined + with it. + + Syntax and results are like for __oo::class__. + + Example: + + % oo::class create example { + self mixin singleton + method foo {} {self} + } + ::example + % [example new] foo + ::oo::Obj22 + % [example new] foo + ::oo::Obj22 + +# AUTHORS + +Donal Fellows, Andreas Kupries + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *oo::util* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[snit(n)](../snit/snit.md) + +# KEYWORDS + +[TclOO](../../../../index.md#tcloo), [callback](../../../../index.md#callback), +[class methods](../../../../index.md#class_methods), [class +variables](../../../../index.md#class_variables), [command +prefix](../../../../index.md#command_prefix), +[currying](../../../../index.md#currying), [method +reference](../../../../index.md#method_reference), [my +method](../../../../index.md#my_method), +[singleton](../../../../index.md#singleton) + +# CATEGORY + +Utility + +# COPYRIGHT + +Copyright © 2011-2015 Andreas Kupries, BSD licensed ADDED embedded/md/tcllib/files/modules/otp/otp.md Index: embedded/md/tcllib/files/modules/otp/otp.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/otp/otp.md @@ -0,0 +1,128 @@ + +[//000000001]: # (otp - RFC 2289 A One-Time Password System) +[//000000002]: # (Generated from file 'otp.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (otp(n) 1.0.0 tcllib "RFC 2289 A One-Time Password System") + +# NAME + +otp - One-Time Passwords + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [EXAMPLES](#section3) + + - [REFERENCES](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require otp ?1.0.0? + +[__::otp::otp-md4__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data*](#1) +[__::otp::otp-md5__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data*](#2) +[__::otp::otp-sha1__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data*](#3) +[__::otp::otp-rmd160__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data*](#4) + +# DESCRIPTION + +This package is an implementation in Tcl of the One-Time Password system as +described in RFC 2289 (1). This system uses message-digest algorithms to +sequentially hash a passphrase to create single-use passwords. The resulting +data is then provided to the user as either hexadecimal digits or encoded using +a dictionary of 2048 words. This system is used by OpenBSD for secure login and +can be used as a SASL mechanism for authenticating users. + +In this implementation we provide support for four algorithms that are included +in the tcllib distribution: MD5 (2), MD4 (3), RIPE-MD160 (4) and SHA-1 (5). + +# COMMANDS + + - __::otp::otp-md4__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data* + + - __::otp::otp-md5__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data* + + - __::otp::otp-sha1__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data* + + - __::otp::otp-rmd160__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data* + +# EXAMPLES + + % otp::otp-md5 -count 99 -seed host67821 "My Secret Pass Phrase" + (binary gibberish) + % otp::otp-md5 -words -count 99 -seed host67821 "My Secret Pass Phrase" + SOON ARAB BURG LIMB FILE WAD + % otp::otp-md5 -hex -count 99 -seed host67821 "My Secret Pass Phrase" + e249b58257c80087 + +# REFERENCES + + 1. Haller, N. et al., "A One-Time Password System", RFC 2289, February 1998. + [http://www.rfc-editor.org/rfc/rfc2289.txt](http://www.rfc-editor.org/rfc/rfc2289.txt) + + 1. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and RSA Data + Security, Inc, April 1992. + ([http://www.rfc-editor.org/rfc/rfc1321.txt](http://www.rfc-editor.org/rfc/rfc1321.txt)) + + 1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992. + ([http://www.rfc-editor.org/rfc/rfc1320.txt](http://www.rfc-editor.org/rfc/rfc1320.txt)) + + 1. H. Dobbertin, A. Bosselaers, B. Preneel, "RIPEMD-160, a strengthened + version of RIPEMD" + [http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf](http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf) + + 1. "Secure Hash Standard", National Institute of Standards and Technology, + U.S. Department Of Commerce, April 1995. + ([http://www.itl.nist.gov/fipspubs/fip180-1.htm](http://www.itl.nist.gov/fipspubs/fip180-1.htm)) + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *otp* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[SASL](../sasl/sasl.md), [md4](../md4/md4.md), [md5](../md5/md5.md), +[ripemd160](../ripemd/ripemd160.md), [sha1](../sha1/sha1.md) + +# KEYWORDS + +[hashing](../../../../index.md#hashing), +[message-digest](../../../../index.md#message_digest), +[password](../../../../index.md#password), [rfc +2289](../../../../index.md#rfc_2289), [security](../../../../index.md#security) + +# CATEGORY + +Hashes, checksums, and encryption + +# COPYRIGHT + +Copyright © 2006, Pat Thoyts ADDED embedded/md/tcllib/files/modules/page/page_intro.md Index: embedded/md/tcllib/files/modules/page/page_intro.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/page/page_intro.md @@ -0,0 +1,69 @@ + +[//000000001]: # (page_intro - Parser generator tools) +[//000000002]: # (Generated from file 'page_intro.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (page_intro(n) 1.0 tcllib "Parser generator tools") + +# NAME + +page_intro - page introduction + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# DESCRIPTION + +*[page](../../../../index.md#page)* (short for *parser generator*) stands for a +set of related packages which help in the construction of parser generators, and +other utilities doing text processing. + +They are mainly geared towards supporting the Tcllib application +__[page](../../apps/page.md)__, with the package __page::pluginmgr__ in a +central role as the plugin management for the application. The other packages +are performing low-level text processing and utility tasks geared towards parser +generation and mainly accessed by __[page](../../apps/page.md)__ through +plugins. + +The packages implementing the plugins are not documented as regular packages, as +they cannot be loaded into a general interpreter, like tclsh, without extensive +preparation of the interpreter. Preparation which is done for them by the plugin +manager. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *page* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[page](../../../../index.md#page), [parser +generator](../../../../index.md#parser_generator), [text +processing](../../../../index.md#text_processing) + +# CATEGORY + +Page Parser Generator + +# COPYRIGHT + +Copyright © 2007 Andreas Kupries ADDED embedded/md/tcllib/files/modules/page/page_pluginmgr.md Index: embedded/md/tcllib/files/modules/page/page_pluginmgr.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/page/page_pluginmgr.md @@ -0,0 +1,802 @@ + +[//000000001]: # (page_pluginmgr - Parser generator tools) +[//000000002]: # (Generated from file 'page_pluginmgr.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (page_pluginmgr(n) 1.0 tcllib "Parser generator tools") + +# NAME + +page_pluginmgr - page plugin manager + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [CONFIG PLUGIN API](#section3) + + - [READER PLUGIN API](#section4) + + - [WRITER PLUGIN API](#section5) + + - [TRANSFORM PLUGIN API](#section6) + + - [PREDEFINED PLUGINS](#section7) + + - [FEATURES](#section8) + + - [Bugs, Ideas, Feedback](#section9) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require page::pluginmgr ?0.2? +package require fileutil + +[__::page::pluginmgr::reportvia__ *cmd*](#1) +[__::page::pluginmgr::report__ *level* *text* ?*from* ?*to*??](#2) +[__::page::pluginmgr::log__ *cmd*](#3) +[__::page::pluginmgr::configuration__ *name*](#4) +[__::page::pluginmgr::reader__ *name*](#5) +[__::page::pluginmgr::rconfigure__ *dict*](#6) +[__::page::pluginmgr::rtimeable__](#7) +[__::page::pluginmgr::rtime__](#8) +[__::page::pluginmgr::rgettime__](#9) +[__::page::pluginmgr::rhelp__](#10) +[__::page::pluginmgr::rlabel__](#11) +[__::page::pluginmgr::read__ *read* *eof* ?*complete*?](#12) +[*read* *num*](#13) +[*eof*](#14) +[*done*](#15) +[__::page::pluginmgr::writer__ *name*](#16) +[__::page::pluginmgr::wconfigure__ *dict*](#17) +[__::page::pluginmgr::wtimeable__](#18) +[__::page::pluginmgr::wtime__](#19) +[__::page::pluginmgr::wgettime__](#20) +[__::page::pluginmgr::whelp__](#21) +[__::page::pluginmgr::wlabel__](#22) +[__::page::pluginmgr::write__ *chan* *data*](#23) +[__::page::pluginmgr::transform__ *name*](#24) +[__::page::pluginmgr::tconfigure__ *id* *dict*](#25) +[__::page::pluginmgr::ttimeable__ *id*](#26) +[__::page::pluginmgr::ttime__ *id*](#27) +[__::page::pluginmgr::tgettime__ *id*](#28) +[__::page::pluginmgr::thelp__ *id*](#29) +[__::page::pluginmgr::tlabel__ *id*](#30) +[__::page::pluginmgr::transform_do__ *id* *data*](#31) +[__page_cdefinition__](#32) +[__page_rfeature__ *name*](#33) +[__page_rtime__](#34) +[__page_rgettime__](#35) +[__page_rlabel__](#36) +[__page_rhelp__](#37) +[__page_roptions__](#38) +[__page_rconfigure__ *option* *value*](#39) +[__page_rrun__](#40) +[__page_read__ *num*](#41) +[__page_read_done__](#42) +[__page_eof__](#43) +[__page_info__ *text* ?*from* ?*to*??](#44) +[__page_warning__ *text* ?*from* ?*to*??](#45) +[__page_error__ *text* ?*from* ?*to*??](#46) +[__page_log_info__ *text*](#47) +[__page_log_warning__ *text*](#48) +[__page_log_error__ *text*](#49) +[__page_wfeature__](#50) +[__page_wtime__](#51) +[__page_wgettime__](#52) +[__page_wlabel__](#53) +[__page_whelp__](#54) +[__page_woptions__](#55) +[__page_wconfigure__ *option* *value*](#56) +[__page_wrun__ *chan* *data*](#57) +[__page_info__ *text* ?*from* ?*to*??](#58) +[__page_warning__ *text* ?*from* ?*to*??](#59) +[__page_error__ *text* ?*from* ?*to*??](#60) +[__page_log_info__ *text*](#61) +[__page_log_warning__ *text*](#62) +[__page_log_error__ *text*](#63) +[__page_tfeature__](#64) +[__page_ttime__](#65) +[__page_tgettime__](#66) +[__page_tlabel__](#67) +[__page_thelp__](#68) +[__page_toptions__](#69) +[__page_tconfigure__ *option* *value*](#70) +[__page_trun__ *chan* *data*](#71) +[__page_info__ *text* ?*from* ?*to*??](#72) +[__page_warning__ *text* ?*from* ?*to*??](#73) +[__page_error__ *text* ?*from* ?*to*??](#74) +[__page_log_info__ *text*](#75) +[__page_log_warning__ *text*](#76) +[__page_log_error__ *text*](#77) + +# DESCRIPTION + +This package provides the plugin manager central to the +__[page](../../apps/page.md)__ application. It manages the various reader, +writer, configuration, and transformation plugins which actually process the +text (read, transform, and write). + +All plugins are loaded into slave interpreters specially prepared for them. +While implemented using packages they need this special environment and are not +usable in a plain interpreter, like tclsh. Because of that they are only +described in general terms in section [PREDEFINED PLUGINS](#section7), and not +documented as regular packages. It is expected that they follow the APIs +specified in the sections + + 1. [CONFIG PLUGIN API](#section3) + + 1. [READER PLUGIN API](#section4) + + 1. [WRITER PLUGIN API](#section5) + + 1. [TRANSFORM PLUGIN API](#section6) + +as per their type. + +# API + + - __::page::pluginmgr::reportvia__ *cmd* + + This command defines the callback command used by + __::page::pluginmgr::report__ (see below) to report input errors and + warnings. The default is to write such reports to the standard error + channel. + + - __::page::pluginmgr::report__ *level* *text* ?*from* ?*to*?? + + This command is used to report input errors and warnings. By default such + reports are written to the standard error. This can be changed by setting a + user-specific callback command with __::page::pluginmgr::reportvia__ (see + above). + + The arguments *level* and *text* specify both the importance of the message, + and the message itself. For the former see the package + __[logger](../log/logger.md)__ for the allowed values. + + The optional argument *from* and *to* can be used by the caller to indicate + the location (or range) in the input where the reported problem occured. + Each is a list containing two elements, the line and the column in the + input, in this order. + + - __::page::pluginmgr::log__ *cmd* + + This command defines a log callback command to be used by loaded plugins for + the reporting of internal errors, warnings, and general information. + Specifying the empty string as callback disables logging. + + Note: The *cmd* has to be created by the __[logger](../log/logger.md)__ + package, or follow the same API as such. + + The command returns the empty string as its result. + + - __::page::pluginmgr::configuration__ *name* + + This command loads the named configuration plugin, retrieves the options + encoded in it, and then immediately unloads it again. + + If the *name* is the path to a file, then this files will be tried to be + loaded as a plugin first, and, if that fails, opened and its contents read + as a list of options and their arguments, separated by spaces, tabs and + newlines, possibly quotes with single and double quotes. + + See section [CONFIG PLUGIN API](#section3) for the API expected of + configuration plugins. + + The result of the command is the list of options retrieved. + + - __::page::pluginmgr::reader__ *name* + + This command loads the named reader plugin and initializes it. The result of + the command is a list of options the plugin understands. + + Only a single reader plugin can be loaded. Loading another reader plugin + causes the previously loaded reader plugin to be de-initialized and + unloaded. + + See section [READER PLUGIN API](#section4) for the API expected of reader + plugins. + + - __::page::pluginmgr::rconfigure__ *dict* + + This commands configures the loaded reader plugin. The options and their + values are provided as a Tcl dictionary. The result of the command is the + empty string. + + - __::page::pluginmgr::rtimeable__ + + This commands checks if the loaded reader plugin is able to collect timing + statistics. The result of the command is a boolean flag. The result is + __true__ if the plugin can be timed, and __false__ otherwise. + + - __::page::pluginmgr::rtime__ + + This command activates the collection of timing statistics in the loaded + reader plugin. + + - __::page::pluginmgr::rgettime__ + + This command retrieves the collected timing statistics of the loaded reader + plugin after it was executed. + + - __::page::pluginmgr::rhelp__ + + This command retrieves the help string of the loaded reader plugin. This is + expected to be in *[doctools](../../../../index.md#doctools)* format. + + - __::page::pluginmgr::rlabel__ + + This command retrieves the human-readable name of the loaded reader plugin. + + - __::page::pluginmgr::read__ *read* *eof* ?*complete*? + + This command invokes the loaded reader plugin to process the input, and + returns the results of the plugin as its own result. The input is accessible + through the callback commands *read*, and *eof*. The optional *done* can be + used to intrecept when the plugin has completed its processing. All + arguments are command prefixes. + + The plugin will invoke the various callbacks in the following situations: + + * *read* *num* + + is invoked whenever input to process is needed, with the number of + characters/bytes it asks for. The result is expected to be the input the + plugin is in need of. + + * *eof* + + is invoked by the plugin to check if the input has reached the of the + stream. The result is expected to be a boolean flag, __true__ when the + input has hit EOF, and __false__ otherwise. + + * *done* + + is invoked when the plugin has completed the processing of the input. + + - __::page::pluginmgr::writer__ *name* + + This command loads the named writer plugin and initializes it. The result of + the command is a list of options the plugin understands. + + Only a single reader plugin can be loaded. Loading another reader plugin + causes the previously loaded reader plugin to be de-initialized and + unloaded. + + See section [WRITER PLUGIN API](#section5) for the API expected of writer + plugins. + + - __::page::pluginmgr::wconfigure__ *dict* + + This commands configures the loaded writer plugin. The options and their + values are provided as a Tcl dictionary. The result of the command is the + empty string. + + - __::page::pluginmgr::wtimeable__ + + This commands checks if the loaded writer plugin is able to measure + execution times. The result of the command is a boolean flag. The result is + __true__ if the plugin can be timed, and __false__ otherwise. + + - __::page::pluginmgr::wtime__ + + This command activates the collection of timing statistics in the loaded + writer plugin. + + - __::page::pluginmgr::wgettime__ + + This command retrieves the collected timing statistics of the loaded writer + plugin after it was executed. + + - __::page::pluginmgr::whelp__ + + This command retrieves the help string of the loaded writer plugin. This is + expected to be in *[doctools](../../../../index.md#doctools)* format. + + - __::page::pluginmgr::wlabel__ + + This command retrieves the human-readable name of the loaded writer plugin. + + - __::page::pluginmgr::write__ *chan* *data* + + The loaded writer plugin is invoked to generate the output. It is given the + *data* to generate the outpout from, and the Tcl handle *chan* of the + channel to write the generated output to. The command returns th empty + string as its result. + + - __::page::pluginmgr::transform__ *name* + + This command loads the named transformation plugin and initializes it. The + result of the command is a 2-element list containing the plugin id and a + list of options the plugin understands, in this order. + + Multiple transformations plugins can be loaded and are identified by + handles. + + See section [TRANSFORM PLUGIN API](#section6) for the API expected of + transformation plugins. + + - __::page::pluginmgr::tconfigure__ *id* *dict* + + This commands configures the identified transformation plugin. The options + and their values are provided as a Tcl dictionary. The result of the command + is the empty string. + + - __::page::pluginmgr::ttimeable__ *id* + + This commands checks if the identified transformation plugin is able to + collect timing statistics. The result of the command is a boolean flag. The + result is __true__ if the plugin can be timed, and __false__ otherwise. + + - __::page::pluginmgr::ttime__ *id* + + This command activates the collection of timing statistics in the identified + transformation plugin. + + - __::page::pluginmgr::tgettime__ *id* + + This command retrieves the collected timing statistics of the identified + transformation plugin after it was executed. + + - __::page::pluginmgr::thelp__ *id* + + This command retrieves the help string of the identified transformation + plugin. This is expected to be in + *[doctools](../../../../index.md#doctools)* format. + + - __::page::pluginmgr::tlabel__ *id* + + This command retrieves the human-readable name of the identified + transformation plugin. + + - __::page::pluginmgr::transform_do__ *id* *data* + + The identified transformation plugin is invoked to process the specified + *data*. The result of the plugin is returned as the result of the command. + +# CONFIG PLUGIN API + +Configuration plugins are expected to provide a single command, described below. + + - __page_cdefinition__ + + This command of a configuration plugin is called by the plugin manager to + execute it. Its result has to be a list of options and values to process. + +Configuration plugins do not expect the environment to provide any special +commands. + +It is expected that a configuration plugin __FOO__ is implemented by the package +__page::config::__FOO____. + +Configuration plugins are loaded, executed, and unloaded in one step, they are +not kept in memory. The command for doing this is +__::page::pluginmgr::configuration__. + +# READER PLUGIN API + +Reader plugins are expected to provide the following commands, described below. + + - __page_rfeature__ *name* + + This command takes a feature *name* and returns a boolean flag indicating + whether the feature is supported by the plugin, or not. The result has to be + __true__ if the feature is supported, and __false__ otherwise. + + See section [FEATURES](#section8) for the possible features the plugin + manager will ask for. + + - __page_rtime__ + + This command is invoked to activate the collection of timing statistics. + + - __page_rgettime__ + + This command is invoked to retrieve the collected timing statistics. + + - __page_rlabel__ + + This command is invoked to retrieve a human-readable label for the plugin. + + - __page_rhelp__ + + This command is invoked to retrieve a help text for plugin. The text is + expected to be in *[doctools](../../../../index.md#doctools)* format. + + - __page_roptions__ + + This command is invoked to retrieve the options understood by the plugin. + + - __page_rconfigure__ *option* *value* + + This command is invoked to reconfigure the plugin, specifically the given + *option* is set to the new *value*. + + - __page_rrun__ + + This command is invoked to process the input stream per the current plugin + configuration. The result of the command is the result of the processing. + +Reader plugins expect the environment to provide the following special commands. + + - __page_read__ *num* + + This command is invoked to read *num* characters/bytes from the input. Its + result has to be read characters/bytes. + + - __page_read_done__ + + This command is invoked to signal that the plugin has completed the + processing of the input. + + - __page_eof__ + + This command is invoked to check if the input stream has reached its end. + Its result has to be a boolean flag, __true__ when the input has reached the + end, __false__ otherwise. + + - __page_info__ *text* ?*from* ?*to*?? + + Invoked to report some information to the user. May indicate a location or + range in the input. Each piece of location data, if provided, is a 2-element + list containing line and column numbers. + + - __page_warning__ *text* ?*from* ?*to*?? + + Invoked to report a warning to the user. May indicate a location or range in + the input. Each piece of location data, if provided, is a 2-element list + containing line and column numbers. + + - __page_error__ *text* ?*from* ?*to*?? + + Invoked to report an error to the user. May indicate a location or range in + the input. Each piece of location data, if provided, is a 2-element list + containing line and column numbers. + + - __page_log_info__ *text* + + Invoked to report some internal information. + + - __page_log_warning__ *text* + + Invoked to report an internal warning. + + - __page_log_error__ *text* + + Invoked to report an internal error. + +It is expected that a reader plugin __FOO__ is implemented by the package +__page::reader::__FOO____. + +Reader plugins are loaded by the command __::page::pluginmgr::reader__. At most +one reader plugin can be kept in memory. + +# WRITER PLUGIN API + +Writer plugins are expected to provide the following commands, described below. + + - __page_wfeature__ + + This command takes a feature *name* and returns a boolean flag indicating + whether the feature is supported by the plugin, or not. The result has to be + __true__ if the feature is supported, and __false__ otherwise. + + See section [FEATURES](#section8) for the possible features the plugin + manager will ask for. + + - __page_wtime__ + + This command is invoked to activate the collection of timing statistics. + + - __page_wgettime__ + + This command is invoked to retrieve the collected timing statistics. + + - __page_wlabel__ + + This command is invoked to retrieve a human-readable label for the plugin. + + - __page_whelp__ + + This command is invoked to retrieve a help text for plugin. The text is + expected to be in *[doctools](../../../../index.md#doctools)* format. + + - __page_woptions__ + + This command is invoked to retrieve the options understood by the plugin. + + - __page_wconfigure__ *option* *value* + + This command is invoked to reconfigure the plugin, specifically the given + *option* is set to the new *value*. + + - __page_wrun__ *chan* *data* + + This command is invoked to process the specified *data* and write it to the + output stream *chan*. The latter is a Tcl channel handle opened for writing. + The result of the command is the empty string. + +Writer plugins expect the environment to provide the following special commands. + + - __page_info__ *text* ?*from* ?*to*?? + + Invoked to report some information to the user. May indicate a location or + range in the input. Each piece of location data, if provided, is a 2-element + list containing line and column numbers. + + - __page_warning__ *text* ?*from* ?*to*?? + + Invoked to report a warning to the user. May indicate a location or range in + the input. Each piece of location data, if provided, is a 2-element list + containing line and column numbers. + + - __page_error__ *text* ?*from* ?*to*?? + + Invoked to report an error to the user. May indicate a location or range in + the input. Each piece of location data, if provided, is a 2-element list + containing line and column numbers. + + - __page_log_info__ *text* + + Invoked to report some internal information. + + - __page_log_warning__ *text* + + Invoked to report an internal warning. + + - __page_log_error__ *text* + + Invoked to report an internal error. + +It is expected that a writer plugin __FOO__ is implemented by the package +__page::writer::__FOO____. + +Writer plugins are loaded by the command __::page::pluginmgr::writer__. At most +one writer plugin can be kept in memory. + +# TRANSFORM PLUGIN API + +page::transform::* Transformation plugins are expected to provide the following +commands, described below. + + - __page_tfeature__ + + This command takes a feature *name* and returns a boolean flag indicating + whether the feature is supported by the plugin, or not. The result has to be + __true__ if the feature is supported, and __false__ otherwise. + + See section [FEATURES](#section8) for the possible features the plugin + manager will ask for. + + - __page_ttime__ + + This command is invoked to activate the collection of timing statistics. + + - __page_tgettime__ + + This command is invoked to retrieve the collected timing statistics. + + - __page_tlabel__ + + This command is invoked to retrieve a human-readable label for the plugin. + + - __page_thelp__ + + This command is invoked to retrieve a help text for plugin. The text is + expected to be in *[doctools](../../../../index.md#doctools)* format. + + - __page_toptions__ + + This command is invoked to retrieve the options understood by the plugin. + + - __page_tconfigure__ *option* *value* + + This command is invoked to reconfigure the plugin, specifically the given + *option* is set to the new *value*. + + - __page_trun__ *chan* *data* + + This command is invoked to process the specified *data* and write it to the + output stream *chan*. The latter is a Tcl channel handle opened for writing. + The result of the command is the empty string. + +Transformation plugins expect the environment to provide the following special +commands. + + - __page_info__ *text* ?*from* ?*to*?? + + Invoked to report some information to the user. May indicate a location or + range in the input. Each piece of location data, if provided, is a 2-element + list containing line and column numbers. + + - __page_warning__ *text* ?*from* ?*to*?? + + Invoked to report a warning to the user. May indicate a location or range in + the input. Each piece of location data, if provided, is a 2-element list + containing line and column numbers. + + - __page_error__ *text* ?*from* ?*to*?? + + Invoked to report an error to the user. May indicate a location or range in + the input. Each piece of location data, if provided, is a 2-element list + containing line and column numbers. + + - __page_log_info__ *text* + + Invoked to report some internal information. + + - __page_log_warning__ *text* + + Invoked to report an internal warning. + + - __page_log_error__ *text* + + Invoked to report an internal error. + +It is expected that a transformation plugin __FOO__ is implemented by the +package __page::transform::__FOO____. + +Transformation plugins are loaded by the command +__::page::pluginmgr::transform__. More than one transformation plugin can be +kept in memory. + +# PREDEFINED PLUGINS + +The following predefined plugins are known, i.e. provided by the page module. + + - Configuration + + * peg + + Returns a set of options to configure the __[page](../../apps/page.md)__ + application for the processing of a PEG grammar and the generation of ME + code. See the packages __grammar_peg__, __grammar_me__ and relations for + more details. + + - Reader + + * hb + + Expects a so-called *half-baked PEG container* as input and returns the + equivalent abstract syntax tree. See the writer plugin *hb* for the + plugin generating this type of input. + + * lemon + + Expects a grammar specification as understood by Richar Hipp's LEMON + parser generator and returns an abstract syntax tree for it. + + * peg + + Expects a grammar specification in the form of a parsing expression + grammar (PEG) and returns an abstract syntax tree for it. + + * ser + + Expect the serialized form of a parsing expression grammar as generated + by the package __[grammar::peg](../grammar_peg/peg.md)__ as input, + converts it into an equivalent abstract syntax tree and returns that. + + * treeser + + Expects the serialized form of a tree as generated by the package + __[struct::tree](../struct/struct_tree.md)__ as input and returns it, + after validation. + + - Writer + + * hb + + Expects an abstract syntax tree for a parsing expression grammar as + input and writes it out in the form of a so-called *half-baked PEG + container*. + + * identity + + Takes any input and writes it as is. + + * mecpu + + Expects symbolic assembler code for the MatchEngine CPU (See the package + __[grammar::me::cpu](../grammar_me/me_cpu.md)__ and relatives) and + writes it out as Tcl code for a parser. + + * me + + Expects an abstract syntax tree for a parsing expression grammar as + input and writes it out as Tcl code for the MatchEngine (See the package + __grammar::me__ and relatives) which parses input in that grammar. + + * null + + Takes any input and writes nothing. The logical equivalent of /dev/null. + + * peg + + Expects an abstract syntax tree for a parsing expression grammar as + input and writes it out in the form of a canonical PEG which can be read + by the reader plugin *peg*. + + * ser + + Expects an abstract syntax tree for a parsing expression grammar as + input and writes it out as a serialized PEG container which can be read + by the reader plugin *ser*. + + * tpc + + Expects an abstract syntax tree for a parsing expression grammar as + input and writes it out as Tcl code initializing a PEG container as + provided by the package __[grammar::peg](../grammar_peg/peg.md)__. + + * tree + + Takes any serialized tree (per package + __[struct::tree](../struct/struct_tree.md)__) as input and writes it out + in a generic indented format. + + - Transformation + + * mecpu + + Takes an abstract syntax tree for a parsing expression grammer as input, + generates symbolic assembler code for the MatchEngine CPU, and returns + that as its result (See the package + __[grammar::me::cpu](../grammar_me/me_cpu.md)__ and relatives). + + * reachable + + Takes an abstract syntax tree for a parsing expression grammer as input, + performs a reachability analysis, and returns the modified and annotated + tree. + + * realizable + + Takes an abstract syntax tree for a parsing expression grammer as input, + performs an analysis of realizability, and returns the modified and + annotated tree. + +# FEATURES + +The plugin manager currently checks the plugins for only one feature, +__timeable__. A plugin supporting this feature is assumed to be able to collect +timing statistics on request. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *page* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[page](../../../../index.md#page), [parser +generator](../../../../index.md#parser_generator), [text +processing](../../../../index.md#text_processing) + +# CATEGORY + +Page Parser Generator + +# COPYRIGHT + +Copyright © 2007 Andreas Kupries ADDED embedded/md/tcllib/files/modules/page/page_util_flow.md Index: embedded/md/tcllib/files/modules/page/page_util_flow.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/page/page_util_flow.md @@ -0,0 +1,126 @@ + +[//000000001]: # (page_util_flow - Parser generator tools) +[//000000002]: # (Generated from file 'page_util_flow.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (page_util_flow(n) 1.0 tcllib "Parser generator tools") + +# NAME + +page_util_flow - page dataflow/treewalker utility + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [FLOW API](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require page::util::flow ?0.1? +package require snit + +[__::page::util::flow__ *start* *flowvar* *nodevar* *script*](#1) +[*flow* __visit__ *node*](#2) +[*flow* __visitl__ *nodelist*](#3) +[*flow* __visita__ *node*...](#4) + +# DESCRIPTION + +This package provides a single utility command for easy dataflow based +manipulation of arbitrary data structures, especially abstract syntax trees. + +# API + + - __::page::util::flow__ *start* *flowvar* *nodevar* *script* + + This command contains the core logic to drive the walking of an arbitrary + data structure which can partitioned into separate parts. Examples of such + structures are trees and graphs. + + The command makes no assumptions at all about the API of the structure to be + walked, except that that its parts, here called *nodes*, are identified by + strings. These strings are taken as is, from the arguments, and the body, + and handed back to the body, without modification. + + Access to the actual data structure, and all decisions regarding which nodes + to visit in what order are delegated to the body of the loop, i.e. the + *script*. + + The body is invoked first for the nodes in the start-set specified via + *start*), and from then on for the nodes the body has requested to be + visited. The command stops when the set of nodes to visit becomes empty. + Note that a node can be visited more than once. The body has complete + control about this. + + The body is invoked in the context of the caller. The variable named by + *nodevar* will be set to the current node, and the variable named by + *flowvar* will be set to the command of the flow object through which the + body can request the nodes to visit next. The API provided by this object is + described in the next section, [FLOW API](#section3). + + Note that the command makes no promises regarding the order in which nodes + are visited, excpt that the nodes requested to be visited by the current + iteration will be visited afterward, in some order. + +# FLOW API + +This section describes the API provided by the flow object made accessible to +the body script of __::page::util::flow__. + + - *flow* __visit__ *node* + + Invoking this method requests that the node *n* is visited after the current + iteration. + + - *flow* __visitl__ *nodelist* + + Invoking this method requests that all the nodes found in the list + *nodelist* are visited after the current iteration. + + - *flow* __visita__ *node*... + + This is the variadic arguments form of the method __visitl__, see above. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *page* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[dataflow](../../../../index.md#dataflow), [graph +walking](../../../../index.md#graph_walking), [page](../../../../index.md#page), +[parser generator](../../../../index.md#parser_generator), [text +processing](../../../../index.md#text_processing), [tree +walking](../../../../index.md#tree_walking) + +# CATEGORY + +Page Parser Generator + +# COPYRIGHT + +Copyright © 2007 Andreas Kupries ADDED embedded/md/tcllib/files/modules/page/page_util_norm_lemon.md Index: embedded/md/tcllib/files/modules/page/page_util_norm_lemon.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/page/page_util_norm_lemon.md @@ -0,0 +1,85 @@ + +[//000000001]: # (page_util_norm_lemon - Parser generator tools) +[//000000002]: # (Generated from file 'page_util_norm_lemon.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (page_util_norm_lemon(n) 1.0 tcllib "Parser generator tools") + +# NAME + +page_util_norm_lemon - page AST normalization, LEMON + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require page::util::norm_lemon ?0.1? +package require snit + +[__::page::util::norm::lemon__ *tree*](#1) + +# DESCRIPTION + +This package provides a single utility command which takes an AST for a lemon +grammar and normalizes it in various ways. The result is called a *Normalized +Lemon Grammar Tree*. + +*Note* that this package can only be used from within a plugin managed by the +package __page::pluginmgr__. + +# API + + - __::page::util::norm::lemon__ *tree* + + This command assumes the *tree* object contains for a lemon grammar. It + normalizes this tree in place. The result is called a *Normalized Lemon + Grammar Tree*. + + The exact operations performed are left undocumented for the moment. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *page* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[graph walking](../../../../index.md#graph_walking), +[lemon](../../../../index.md#lemon), +[normalization](../../../../index.md#normalization), +[page](../../../../index.md#page), [parser +generator](../../../../index.md#parser_generator), [text +processing](../../../../index.md#text_processing), [tree +walking](../../../../index.md#tree_walking) + +# CATEGORY + +Page Parser Generator + +# COPYRIGHT + +Copyright © 2007 Andreas Kupries ADDED embedded/md/tcllib/files/modules/page/page_util_norm_peg.md Index: embedded/md/tcllib/files/modules/page/page_util_norm_peg.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/page/page_util_norm_peg.md @@ -0,0 +1,128 @@ + +[//000000001]: # (page_util_norm_peg - Parser generator tools) +[//000000002]: # (Generated from file 'page_util_norm_peg.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (page_util_norm_peg(n) 1.0 tcllib "Parser generator tools") + +# NAME + +page_util_norm_peg - page AST normalization, PEG + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require page::util::norm_peg ?0.1? +package require snit + +[__::page::util::norm::peg__ *tree*](#1) + +# DESCRIPTION + +This package provides a single utility command which takes an AST for a parsing +expression grammar and normalizes it in various ways. The result is called a +*Normalized PE Grammar Tree*. + +*Note* that this package can only be used from within a plugin managed by the +package __page::pluginmgr__. + +# API + + - __::page::util::norm::peg__ *tree* + + This command assumes the *tree* object contains for a parsing expression + grammar. It normalizes this tree in place. The result is called a + *Normalized PE Grammar Tree*. + + The following operations are performd + + The data for all terminals is stored in their grandparental nodes. The + terminal nodes and their parents are removed. Type information is dropped. + + All nodes which have exactly one child are irrelevant and are removed, with + the exception of the root node. The immediate child of the root is + irrelevant as well, and removed as well. + + The name of the grammar is moved from the tree node it is stored in to an + attribute of the root node, and the tree node removed. + + The node keeping the start expression separate is removed as irrelevant and + the root node of the start expression tagged with a marker attribute, and + its handle saved in an attribute of the root node for quick access. + + Nonterminal hint information is moved from nodes into attributes, and the + now irrelevant nodes are deleted. + + *Note:* This transformation is dependent on the removal of all nodes with + exactly one child, as it removes the all 'Attribute' nodes already. + Otherwise this transformation would have to put the information into the + grandparental node. + + The default mode given to the nonterminals is __value__. + + Like with the global metadata definition specific information is moved out + out of nodes into attributes, the now irrelevant nodes are deleted, and the + root nodes of all definitions are tagged with marker attributes. This + provides us with a mapping from nonterminal names to their defining nodes as + well, which is saved in an attribute of the root node for quick reference. + + At last the range in the input covered by a definition is computed. The left + extent comes from the terminal for the nonterminal symbol it defines. The + right extent comes from the rightmost child under the definition. While this + not an expression tree yet the location data is sound already. + + The remaining nodes under all definitions are transformed into proper + expression trees. First character ranges, followed by unary operations, + characters, and nonterminals. At last the tree is flattened by the removal + of superfluous inner nodes. + + The order matters, to shed as much nodes as possible early, and to avoid + unnecessary work later. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *page* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[PEG](../../../../index.md#peg), [graph +walking](../../../../index.md#graph_walking), +[normalization](../../../../index.md#normalization), +[page](../../../../index.md#page), [parser +generator](../../../../index.md#parser_generator), [text +processing](../../../../index.md#text_processing), [tree +walking](../../../../index.md#tree_walking) + +# CATEGORY + +Page Parser Generator + +# COPYRIGHT + +Copyright © 2007 Andreas Kupries ADDED embedded/md/tcllib/files/modules/page/page_util_peg.md Index: embedded/md/tcllib/files/modules/page/page_util_peg.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/page/page_util_peg.md @@ -0,0 +1,146 @@ + +[//000000001]: # (page_util_peg - Parser generator tools) +[//000000002]: # (Generated from file 'page_util_peg.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (page_util_peg(n) 1.0 tcllib "Parser generator tools") + +# NAME + +page_util_peg - page PEG transformation utilities + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require page::util::peg ?0.1? +package require snit + +[__::page::util::peg::symbolNodeOf__ *tree* *node*](#1) +[__::page::util::peg::symbolOf__ *tree* *node*](#2) +[__::page::util::peg::updateUndefinedDueRemoval__ *tree*](#3) +[__::page::util::peg::flatten__ *treequery* *tree*](#4) +[__::page::util::peg::getWarnings__ *tree*](#5) +[__::page::util::peg::printWarnings__ *msg*](#6) +[__::page::util::peg::peOf__ *tree* *eroot*](#7) +[__::page::util::peg::printTclExpr__ *pe*](#8) + +# DESCRIPTION + +This package provides a few common operations to PEG transformations. They +assume a *Normalized PE Grammar Tree* as input, see the package +__page::util::norm::peg__, possibly augmented with attributes coming from +transformations not in conflict with the base definition. + +# API + + - __::page::util::peg::symbolNodeOf__ *tree* *node* + + Given an arbitrary expression *node* in the AST *tree* it determines the + node (itself or an ancestor) containing the name of the nonterminal symbol + the node belongs to, and returns its id. The result is either the root of + the tree (for the start expression), or a definition node. + + - __::page::util::peg::symbolOf__ *tree* *node* + + As __::page::util::peg::symbolNodeOf__, but returns the symbol name instead + of the node. + + - __::page::util::peg::updateUndefinedDueRemoval__ *tree* + + The removal of nodes in the AST *tree* can cause symbols to lose one or more + users. + + A used by B and C, + B is reachable, + C is not, + + so A now loses the node in the expression for C calling it, + or rather, not calling it anymore. + + This command updates the cross-references and which nonterminals are now + undefined. + + - __::page::util::peg::flatten__ *treequery* *tree* + + This commands flattens nested sequence and choice operators in the AST + *tree*, re-using the __[treeql](../treeql/treeql.md)__ object *treequery* to + run the query determining which nodes to cut. + + - __::page::util::peg::getWarnings__ *tree* + + This command looks at the attributes of the AST *tree* for problems with the + grammar and issues warnings. They do not prevent us from writing the + grammar, but still represent problems with it the user should be made aware + of. + + The result of the command is a dictionary mapping nonterminal names to their + associated warnings. + + - __::page::util::peg::printWarnings__ *msg* + + The argument of the command is a dictionary mapping nonterminal names to + their associated warnings, as generated by, for example, the command + __::page::util::peg::getWarnings__. + + The warnings contained therein are formatted and then printed via the log + command __page_info__. This means that this command can be used only from + within a plugin managed by the package __page::pluginmgr__. + + - __::page::util::peg::peOf__ *tree* *eroot* + + This command converts the parsing expression starting at the node *eroot* in + the AST *tree* into a nested list. The exact syntax of this list specified + by the package __[grammar::peg](../grammar_peg/peg.md)__. + + - __::page::util::peg::printTclExpr__ *pe* + + This command converts the parsing expression contained in the nested list + *pe* into a Tcl string which can be placed into a Tcl script. See the + package __[grammar::peg](../grammar_peg/peg.md)__ for the exact syntax of + *pe*. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *page* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[PEG](../../../../index.md#peg), [page](../../../../index.md#page), [parser +generator](../../../../index.md#parser_generator), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [text +processing](../../../../index.md#text_processing), +[transformation](../../../../index.md#transformation) + +# CATEGORY + +Page Parser Generator + +# COPYRIGHT + +Copyright © 2007 Andreas Kupries ADDED embedded/md/tcllib/files/modules/page/page_util_quote.md Index: embedded/md/tcllib/files/modules/page/page_util_quote.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/page/page_util_quote.md @@ -0,0 +1,105 @@ + +[//000000001]: # (page_util_quote - Parser generator tools) +[//000000002]: # (Generated from file 'page_util_quote.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (page_util_quote(n) 1.0 tcllib "Parser generator tools") + +# NAME + +page_util_quote - page character quoting utilities + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require page::util::quote ?0.1? +package require snit + +[__::page::util::quote::unquote__ *char*](#1) +[__::page::util::quote::quote'tcl__ *char*](#2) +[__::page::util::quote::quote'tclstr__ *char*](#3) +[__::page::util::quote::quote'tclcom__ *char*](#4) + +# DESCRIPTION + +This package provides a few utility commands to convert characters into various +forms. + +# API + + - __::page::util::quote::unquote__ *char* + + A character, as stored in an abstract syntax tree by a PEG processor (See + the packages __grammar::peg::interpreter__, __grammar::me__, and their + relations), i.e. in some quoted form, is converted into the equivalent Tcl + character. The character is returned as the result of the command. + + - __::page::util::quote::quote'tcl__ *char* + + This command takes a Tcl character (internal representation) and converts it + into a string which is accepted by the Tcl parser, will regenerate the + character in question and is 7bit ASCII. The string is returned as the + result of this command. + + - __::page::util::quote::quote'tclstr__ *char* + + This command takes a Tcl character (internal representation) and converts it + into a string which is accepted by the Tcl parser and will generate a human + readable representation of the character in question. The string is returned + as the result of this command. + + The string does not use any unprintable characters. It may use + backslash-quoting. High UTF characters are quoted to avoid problems with the + still prevalent ascii terminals. It is assumed that the string will be used + in a double-quoted environment. + + - __::page::util::quote::quote'tclcom__ *char* + + This command takes a Tcl character (internal representation) and converts it + into a string which is accepted by the Tcl parser when used within a Tcl + comment. The string is returned as the result of this command. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *page* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[page](../../../../index.md#page), [parser +generator](../../../../index.md#parser_generator), +[quoting](../../../../index.md#quoting), [text +processing](../../../../index.md#text_processing) + +# CATEGORY + +Page Parser Generator + +# COPYRIGHT + +Copyright © 2007 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pki/pki.md Index: embedded/md/tcllib/files/modules/pki/pki.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pki/pki.md @@ -0,0 +1,240 @@ + +[//000000001]: # (pki - public key encryption) +[//000000002]: # (Generated from file 'pki.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pki(n) 0.10 tcllib "public key encryption") + +# NAME + +pki - Implementation of the public key cipher + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [EXAMPLES](#section3) + + - [REFERENCES](#section4) + + - [AUTHORS](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pki ?0.10? + +[__::pki::encrypt__ ?*-binary*? ?*-hex*? ?*-pad*? ?*-nopad*? ?*-priv*? ?*-pub*? ?*--*? *input* *key*](#1) +[__::pki::decrypt__ ?*-binary*? ?*-hex*? ?*-unpad*? ?*-nounpad*? ?*-priv*? ?*-pub*? ?*--*? *input* *key*](#2) +[__::pki::sign__ *input* *key* ?*algo*?](#3) +[__::pki::verify__ *signedmessage* *plaintext* *key* ?*algo*?](#4) +[__::pki::key__ *key* ?*password*? ?*encodePem*?](#5) +[__::pki::pkcs::parse_key__ *key* ?*password*?](#6) +[__::pki::x509::parse_cert__ *cert*](#7) +[__::pki::rsa::generate__ *bitlength* ?*exponent*?](#8) +[__::pki::x509::verify_cert__ *cert* *trustedcerts* ?*intermediatecerts*?](#9) +[__::pki::x509::validate_cert__ *cert* ?__-sign_message__ *dn_of_signer*? ?__-encrypt_message__ *dn_of_signer*? ?__-sign_cert__ *dn_to_be_signed* *ca_depth*? ?__-ssl__ *dn*?](#10) +[__::pki::pkcs::create_csr__ *keylist* *namelist* ?*encodePem*? ?*algo*?](#11) +[__::pki::pkcs::parse_csr__ *csr*](#12) +[__::pki::x509::create_cert__ *signreqlist* *cakeylist* *serial_number* *notBefore* *notAfter* *isCA* *extensions* ?*encodePem*? ?*algo*?](#13) + +# DESCRIPTION + +# COMMANDS + + - __::pki::encrypt__ ?*-binary*? ?*-hex*? ?*-pad*? ?*-nopad*? ?*-priv*? ?*-pub*? ?*--*? *input* *key* + + Encrypt a message using PKI (probably RSA). Requires the caller to specify + either __-priv__ to encrypt with the private key or __-pub__ to encrypt with + the public key. The default option is to pad and return in hex. One of + __-pub__ or __-priv__ must be specified. The __-hex__ option causes the data + to be returned in encoded as a hexidecimal string, while the __-binary__ + option causes the data to be returned as a binary string. If they are + specified multiple times, the last one specified is used. The __-pad__ + option causes the data to be padded per PKCS#1 prior to being encrypted. The + __-nopad__ inhibits this behaviour. If they are specified multiple times, + the last one specified is used. The input to encrypt is specified as + *input*. The *key* parameter, holding the key to use, is a return value from + either __::pki::pkcs::parse_key__, __::pki::x509::parse_cert__, or + __::pki::rsa::generate__. + + Mapping to OpenSSL's __openssl__ application: + + "openssl rsautl -encrypt" == "::pki::encrypt -binary -pub" + + "openssl rsautl -sign" == "::pki::encrypt -binary -priv" + + - __::pki::decrypt__ ?*-binary*? ?*-hex*? ?*-unpad*? ?*-nounpad*? ?*-priv*? ?*-pub*? ?*--*? *input* *key* + + Decrypt a message using PKI (probably RSA). See __::pki::encrypt__ for + option handling. + + Mapping to OpenSSL's __openssl__ application: + + "openssl rsautl -decrypt" == "::pki::decrypt -binary -priv" + + "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. + + - __::pki::verify__ *signedmessage* *plaintext* *key* ?*algo*? + + Verify a digital signature using a public *key*. Returns true or false. + + - __::pki::key__ *key* ?*password*? ?*encodePem*? + + Convert a key structure into a serialized PEM (default) or DER encoded + private key suitable for other applications. For RSA keys this means PKCS#1. + + - __::pki::pkcs::parse_key__ *key* ?*password*? + + Convert a PKCS#1 private *key* into a usable key, i.e. one which can be used + as argument for __::pki::encrypt__, __::pki::decrypt__, __::pki::sign__, and + __::pki::verify__. + + - __::pki::x509::parse_cert__ *cert* + + Convert an X.509 certificate to a usable (public) key, i.e. one which can be + used as argument for __::pki:encrypt__, __::pki::decrypt__, and + __::pki::verify__. The *cert* argument can be either PEM or DER encoded. + + - __::pki::rsa::generate__ *bitlength* ?*exponent*? + + Generate a new RSA key pair, the parts of which can be used as argument for + __::pki::encrypt__, __::pki::decrypt__, __::pki::sign__, and + __::pki::verify__. The *bitlength* argument is the length of the public key + modulus. The *exponent* argument should generally not be specified unless + you really know what you are doing. + + - __::pki::x509::verify_cert__ *cert* *trustedcerts* ?*intermediatecerts*? + + Verify that a trust can be found between the certificate specified in the + *cert* argument and one of the certificates specified in the list of + certificates in the *trustedcerts* argument. (Eventually the chain can be + through untrusted certificates listed in the *intermediatecerts* argument, + but this is currently unimplemented). The certificates specified in the + *cert* and *trustedcerts* option should be parsed (from + __::pki::x509::parse_cert__). + + - __::pki::x509::validate_cert__ *cert* ?__-sign_message__ *dn_of_signer*? ?__-encrypt_message__ *dn_of_signer*? ?__-sign_cert__ *dn_to_be_signed* *ca_depth*? ?__-ssl__ *dn*? + + Validate that a certificate is valid to be used in some capacity. If + multiple options are specified they must all be met for this procedure to + return "true". Currently, only the __-sign_cert__ option is functional. + Arguments for the __-sign_cert__ option are *dn_to_be_signed* and + *ca_depth*. The *dn_to_be_signed* is the distinguished from the subject of a + certificate to verify that the certificate specified in the *cert* argument + can sign. The *ca_depth* argument is used to indicate at which depth the + verification should be done at. Some certificates are limited to how far + down the chain they can be used to verify a given certificate. + + - __::pki::pkcs::create_csr__ *keylist* *namelist* ?*encodePem*? ?*algo*? + + Generate a certificate signing request from a key pair specified in the + *keylist* argument. The *namelist* argument is a list of "name" followed by + "value" pairs to encoding as the requested distinguished name in the CSR. + The *encodePem* option specifies whether or not the result should be PEM + encoded or DER encoded. A "true" value results in the result being PEM + encoded, while any other value 9results in the the result being DER encoded. + DER encoding is the default. The *algo* argument specifies the hashing + algorithm we should use to sign this certificate signing request with. The + default is "sha1". Other possible values include "md5" and "sha256". + + - __::pki::pkcs::parse_csr__ *csr* + + Parse a Certificate Signing Request. The *csr* argument can be either PEM or + DER encoded. + + - __::pki::x509::create_cert__ *signreqlist* *cakeylist* *serial_number* *notBefore* *notAfter* *isCA* *extensions* ?*encodePem*? ?*algo*? + + Sign a signing request (usually from __::pki::pkcs::create_csr__ or + __::pki::pkcs::parse_csr__) with a Certificate Authority (CA) certificate. + The *signreqlist* argument should be the parsed signing request. The + *cakeylist* argument should be the parsed CA certificate. The + *serial_number* argument should be a serial number unique to this + certificate from this certificate authority. The *notBefore* and *notAfter* + arguments should contain the time before and after which (respectively) the + certificate should be considered invalid. The time should be encoded as + something __clock format__ will accept (i.e., the results of __clock + seconds__ and __clock add__). The *isCA* argument is a boolean argumen + describing whether or not the signed certificate should be a a CA + certificate. If specified as true the "id-ce-basicConstraints" extension is + added with the arguments of "critical" being true, "allowCA" being true, and + caDepth being -1 (infinite). The *extensions* argument is a list of + extensions and their parameters that should be encoded into the created + certificate. Currently only one extension is understood + ("id-ce-basicConstraints"). It accepts three arguments *critical* *allowCA* + *caDepth*. The *critical* argument to this extension (and any extension) + whether or not the validator should reject the certificate as invalid if it + does not understand the extension (if set to "true") or should ignore the + extension (if set to "false"). The *allowCA* argument is used to specify as + a boolean value whether or not we can be used a certificate authority (CA). + The *caDepth* argument indicates how many children CAs can be children of + this CA in a depth-wise fashion. A value of "0" for the *caDepth* argument + means that this CA cannot sign a CA certificate and have the result be + valid. A value of "-1" indicates infinite depth. + +# EXAMPLES + +# REFERENCES + +# AUTHORS + +Roy Keene + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *rsa* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[aes(n)](../aes/aes.md), [blowfish(n)](../blowfish/blowfish.md), +[des(n)](../des/des.md), [md5(n)](../md5/md5.md), [sha1(n)](../sha1/sha1.md) + +# KEYWORDS + +[cipher](../../../../index.md#cipher), [data +integrity](../../../../index.md#data_integrity), +[encryption](../../../../index.md#encryption), [public key +cipher](../../../../index.md#public_key_cipher), +[rsa](../../../../index.md#rsa), [security](../../../../index.md#security) + +# CATEGORY + +Hashes, checksums, and encryption + +# COPYRIGHT + +Copyright © 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries ADDED embedded/md/tcllib/files/modules/pluginmgr/pluginmgr.md Index: embedded/md/tcllib/files/modules/pluginmgr/pluginmgr.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pluginmgr/pluginmgr.md @@ -0,0 +1,389 @@ + +[//000000001]: # (pluginmgr - Plugin management) +[//000000002]: # (Generated from file 'pluginmgr.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pluginmgr(n) 0.3 tcllib "Plugin management") + +# NAME + +pluginmgr - Manage a plugin + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [PUBLIC API](#section2) + + - [PACKAGE COMMANDS](#subsection1) + + - [OBJECT COMMAND](#subsection2) + + - [OBJECT METHODS](#subsection3) + + - [OBJECT CONFIGURATION](#subsection4) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require pluginmgr ?0.3? + +[__::pluginmgr__ *objectName* ?*option value*...?](#1) +[__::pluginmgr::paths__ *objectName* *name*...](#2) +[__objectName__ __method__ ?*arg arg ...*?](#3) +[*objectName* __clone__](#4) +[*objectName* __configure__](#5) +[*objectName* __configure__ *option*](#6) +[*objectName* __configure__ __-option__ *value*...](#7) +[*objectName* __cget__ __-option__](#8) +[*objectName* __destroy__](#9) +[*objectName* __do__ *arg*...](#10) +[*objectName* __interpreter__](#11) +[*objectName* __plugin__](#12) +[*objectName* __load__ *string*](#13) +[*objectName* __unload__](#14) +[*objectName* __list__](#15) +[*objectName* __path__ *path*](#16) +[*objectName* __paths__](#17) + +# DESCRIPTION + +This package provides commands and objects for the generic management of plugins +which can be loaded into an application. + +To avoid the implementation of yet another system to locate Tcl code the system +provides by this package is built on top of the regular package management +system. Each plugin is considered as a package and a simple invokation of +__package require__ is enough to locate and load it, if it exists. The only time +we will need additional paths is when a plugin manager is part of a wrapped +application and has to be able to search for plugins existing outside of that +application. For this situation the package provides a command to create a +general set of such paths based on names for the plugin manager and/or +application in question. + +The main contribution of this package is a generic framework which allows the +easy declaration of + + 1. How to translate a plugin name to the name of the package implementing it, + and vice versa. + + 1. The list of commands a plugin has to provide as API, and also of more + complex checks as code. + + 1. The list of commands expected by the plugin from the environment. + +This then allows the easy generation of plugin managers customized to particular +types of plugins for an application. + +It should be noted that all plugin code is considered untrusted and will always +be executed within a safe interpreter. The interpreter is enabled enough to +allow plugins the loading of all additional packages they may need. + +# PUBLIC API + +## PACKAGE COMMANDS + + - __::pluginmgr__ *objectName* ?*option value*...? + + This command creates a new plugin manager object with an associated Tcl + command whose name is *objectName*. This + *[object](../../../../index.md#object)* command is explained in full detail + in the sections [OBJECT COMMAND](#subsection2) and [OBJECT + METHODS](#subsection3). The object command will be created under the current + namespace if the *objectName* is not fully qualified, and in the specified + namespace otherwise. + + The options and their values coming after the name of the object are used to + set the initial configuration of the mamager object, specifying the + applicable plugins and their API. + + - __::pluginmgr::paths__ *objectName* *name*... + + This utility command adds a set of paths to the specified object, based on + the given *name*s. It will search for: + + The environment variable __*name*_PLUGINS__. Its contents will be + interpreted as a list of package paths. The entries have to be separated by + either __:__ (unix) or __;__ (windows). + + The name will be converted to upper-case letters. + + The registry entry "HKEY_LOCAL_MACHINE\SOFTWARE\*name*\PLUGINS". Its + contents will be interpreted as a list of package paths. The entries have to + be separated by __;__. This item is considered only when on Windows (tm). + + The casing of letters is not changed. + + The registry entry "HKEY_CURRENT_USER\SOFTWARE\*name*\PLUGINS". Its contents + will be interpreted as a list of package paths. The entries have to be + separated by __;__. This item is considered only when on Windows (tm). + + The casing of letters is not changed. + + The directory "~/.*name*/plugin". + + The directory "~/.*name*/plugins". + + The casing of letters is not changed. + + and add all the paths found that way to the list of package paths maintained + by the object. + + If *name* is namespaced each item in the list will be repeated per prefix of + *name*, with conversion of :-sequences into the proper separator (underscore + for environment variables, backslash for registry entries, and / for + directories). + + Examples: + + ::pluginmgr::paths ::obj docidx + + => env DOCIDX_PLUGINS + reg HKEY_LOCAL_MACHINE\SOFTWARE\docidx\PLUGINS + reg HKEY_CURRENT_USER\SOFTWARE\docidx\PLUGINS + path ~/.docidx/plugins + + ::pluginmgr::paths ::obj doctools::idx + + => env DOCTOOLS_PLUGINS + env DOCTOOLS_IDX_PLUGINS + reg HKEY_LOCAL_MACHINE\SOFTWARE\doctools\PLUGINS + reg HKEY_LOCAL_MACHINE\SOFTWARE\doctools\idx\PLUGINS + reg HKEY_CURRENT_USER\SOFTWARE\doctools\PLUGINS + reg HKEY_CURRENT_USER\SOFTWARE\doctools\idx\PLUGINS + path ~/.doctools/plugin + path ~/.doctools/idx/plugin + +## OBJECT COMMAND + +All commands created by the command __::pluginmgr__ (See section [PACKAGE +COMMANDS](#subsection1)) have the following general form and may be used to +invoke various operations on their plugin manager object. + + - __objectName__ __method__ ?*arg arg ...*? + + The method __method__ and its *arg*'uments determine the exact behavior of + the command. See section [OBJECT METHODS](#subsection3) for the detailed + specifications. + +## OBJECT METHODS + + - *objectName* __clone__ + + This method creates a new plugin management object and returns the + associated object command. The generated object is a clone of the object the + method was invoked on. I.e. the new object will have the same configuration + as the current object. With regard to state, if the current object has a + plugin loaded then this plugin and all associated state is moved to the + generated clone and the current object is reset into the base state (no + plugin loaded). In this manner a configured plugin manager is also a factory + for loaded plugins. + + - *objectName* __configure__ + + The method returns a list of all known options and their current values when + called without any arguments. + + - *objectName* __configure__ *option* + + The method behaves like the method __cget__ when called with a single + argument and returns the value of the option specified by said argument. + + - *objectName* __configure__ __-option__ *value*... + + The method reconfigures the specified __option__s of the object, setting + them to the associated *value*s, when called with an even number of + arguments, at least two. + + The legal options are described in the section [OBJECT + CONFIGURATION](#subsection4). + + - *objectName* __cget__ __-option__ + + This method expects a legal configuration option as argument and will return + the current value of that option for the object the method was invoked for. + + The legal configuration options are described in section [OBJECT + CONFIGURATION](#subsection4). + + - *objectName* __destroy__ + + This method destroys the object it is invoked for. + + - *objectName* __do__ *arg*... + + This method interprets its list of arguments as the words of a command and + invokes this command in the execution context of the plugin. The result of + the invoked command is made the result of the method. The call will fail + with an error if no valid plugin has been loaded into the manager object. + + - *objectName* __interpreter__ + + This method returns the handle of the safe interpreter the current plugin is + loaded into. An empty string as return value signals that the manager + currently has no valid plugin loaded. + + - *objectName* __plugin__ + + This method returns the name of the plugin currently loaded. An empty string + as return value signals that the manager currently has no valid plugin + loaded. + + - *objectName* __load__ *string* + + This method loads, validates, and initializes a named plugin into the + manager object. + + The algorithm to locate and load the plugin employed is: + + If the *string* contains the path to an existing file then this file is + taken as the implementation of the plugin. + + Otherwise the plugin name is translated into a package name via the value of + the option __-pattern__ and then loaded through the regular package + management. + + The load fails. + + The algorithm to validate and initialize the loaded code is: + + If the option __-api__ is non-empty introspection commands are used to + ascertain that the plugin provides the listed commands. + + If the option __-check__ is non-empty the specified command prefix is + called. + + If either of the above fails the candidate plugin is unloaded again + + Otherwise all the commands specified via the option __-cmds__ are installed + in the plugin. + + A previously loaded plugin is discarded, but only if the new plugin was + found and sucessfully validated and initialized. Note that there will be no + intereference between old and new plugin as both will be put into separate + safe interpreters. + + - *objectName* __unload__ + + This method unloads the currently loaded plugin. It returns the empty + string. The call will be silently ignored if no plugin is loaded at all. + + - *objectName* __list__ + + This method uses the contents of the option __-pattern__ to find all + packages which can be plugins under the purview of this manager object. It + translates their names into plugin names and returns a list containing them. + + - *objectName* __path__ *path* + + This methods adds the specified *path* to the list of additional package + paths to look at when searching for a plugin. It returns the empty string. + Duplicate paths are ignored, i.e. each path is added only once. Paths are + made absolute, but are not normalized. + + - *objectName* __paths__ + + This method returns a list containing all additional paths which have been + added to the plugin manager object since its creation. + +## OBJECT CONFIGURATION + +All plugin manager objects understand the following configuration options: + + - __-pattern__ *string* + + The value of this option is a glob pattern which has to contain exactly one + '*'-operator. All packages whose names match this pattern are the plugins + recognized by the manager object. And vice versa, the replacement of the + '*'-operator with a plugin name will yield the name of the package + implementing that plugin. + + This option has no default, except if option __-name__ was set. It has to be + set before attempting to load a plugin, either directly, or through option + __-name__. + + - __-api__ *list* + + The value of this option is a list of command names, and any plugin loaded + has to provide these commands. Names which are not fully qualified are + considered to be rooted in the global namespace. If empty no expectations + are made on the plugin. The default value is the empty list. + + - __-check__ *cmdprefix* + + The value of this option is interpreted as a command prefix. Its purpose is + to perform complex checks on a loaded plugin package to validate it, which + go beyond a simple list of provided commands. + + It is called with the manager object command as the only argument and has to + return a boolean value. A value of __true__ will be interpreted to mean that + the candidate plugin passed the test. The call will happen if and only if + the candidate plugin already passed the basic API check specified through + the option __-api__. + + The default value is the empty list, which causes the manager object to + suppress the call and to assume the candidate plugin passes. + + - __-cmds__ *dict* + + The value of this option is a dictionary. It specifies the commands which + will be made available to the plugin (as keys), and the trusted commands in + the environment which implement them (as values). The trusted commands will + be executed in the interpreter specified by the option __-cmdip__. The + default value is the empty dictionary. + + - __-cmdip__ *ipspec* + + The value of this option is the path of the interpreter where the trusted + commands given to the plugin will be executed in. The default is the empty + string, referring to the current interpreter. + + - __-setup__ *cmdprefix* + + The value of this option is interpreted as a command prefix. + + It is called whenever a new safe interpreter for a plugin has been created, + but before a plugin is loaded. It is provided with the manager object + command and the interpreter handle as its only arguments. Any return value + will be ignored. + + Its purpose is give a user of the plugin management the ability to define + commands, packages, etc. a chosen plugin may need while being loaded. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pluginmgr* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[plugin management](../../../../index.md#plugin_management), [plugin +search](../../../../index.md#plugin_search) + +# CATEGORY + +Programming tools + +# COPYRIGHT + +Copyright © 2005 Andreas Kupries ADDED embedded/md/tcllib/files/modules/png/png.md Index: embedded/md/tcllib/files/modules/png/png.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/png/png.md @@ -0,0 +1,206 @@ + +[//000000001]: # (png - Image manipulation) +[//000000002]: # (Generated from file 'png.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (png(n) 0.3 tcllib "Image manipulation") + +# NAME + +png - PNG querying and manipulation of meta data + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require crc32 +package require png ?0.3? + +[__::png::validate__ *file*](#1) +[__::png::isPNG__ *file*](#2) +[__::png::imageInfo__ *file*](#3) +[__::png::getTimestamp__ *file*](#4) +[__::png::setTimestamp__ *file* *time*](#5) +[__::png::getComments__ *file*](#6) +[__::png::removeComments__ *file*](#7) +[__::png::addComment__ *file* *keyword* *text*](#8) +[__::png::addComment__ *file* *keyword* *lang* *keyword2* *text*](#9) +[__::png::getPixelDimension__ *file*](#10) +[__::png::image__ *file*](#11) +[__::png::write__ *file* *data*](#12) + +# DESCRIPTION + +This package provides commands to query and modify PNG images. PNG stands for +*Portable Network Graphics* and is specified at +[http://www.libpng.org/pub/png/spec/1.2](http://www.libpng.org/pub/png/spec/1.2). + +# COMMANDS + + - __::png::validate__ *file* + + Returns a value indicating if *file* is a valid PNG file. The file is + checked for PNG signature, each chunks checksum is verified, existence of a + data chunk is verified, first chunk is checked for header, last chunk is + checked for ending. Things *not* checked for are: validity of values within + a chunk, multiple header chunks, noncontiguous data chunks, end chunk before + actual eof. This procedure can take lots of time. + + Possible return values: + + * OK + + File is a valid PNG file. + + * SIG + + no/broken PNG signature. + + * BADLEN + + corrupt chunk length. + + * EOF + + premature end of file. + + * NOHDR + + missing header chunk. + + * CKSUM + + crc mismatch. + + * NODATA + + missing data chunk(s). + + * NOEND + + missing end marker. + + - __::png::isPNG__ *file* + + Returns a boolean value indicating if the file *file* starts with a PNG + signature. This is a much faster and less intensive check than + __::png::validate__ as it does not check if the PNG data is valid. + + - __::png::imageInfo__ *file* + + Returns a dictionary with keys __width__, __height__, __depth__, __color__, + __compression__, __filter__, and __interlace__. The values are the + associated properties of the PNG image in *file*. Throws an error if file is + not a PNG image, or if the checksum of the header is invalid. For + information on interpreting the values for the returned properties see + [http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html](http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html). + + - __::png::getTimestamp__ *file* + + Returns the epoch time if a timestamp chunk is found in the PNG image + contained in the *file*, otherwise returns the empty string. Does not + attempt to verify the checksum of the timestamp chunk. Throws an error if + the *file* is not a valid PNG image. + + - __::png::setTimestamp__ *file* *time* + + Writes a new timestamp to the *file*, either replacing the old timestamp, or + adding one just before the data chunks if there was no previous timestamp. + *time* is the new time in the gmt epoch format. Throws an error if *file* is + not a valid PNG image. + + - __::png::getComments__ *file* + + Currently supports only uncompressed comments. Does not attempt to verify + the checksums of the comment chunks. Returns a list where each element is a + comment. Each comment is itself a list. The list for a plain text comment + consists of 2 elements: the human readable keyword, and the text data. A + unicode (international) comment consists of 4 elements: the human readable + keyword, the language identifier, the translated keyword, and the unicode + text data. Throws an error if *file* is not a valid PNG image. + + - __::png::removeComments__ *file* + + Removes all comments from the PNG image in *file*. Beware - This uses memory + equal to the file size minus comments, to hold the intermediate result. + Throws an error if *file* is not a valid PNG image. + + - __::png::addComment__ *file* *keyword* *text* + + Adds a plain *text* comment to the PNG image in *file*, just before the + first data chunk. Will throw an error if no data chunk is found. *keyword* + has to be less than 80 characters long to conform to the PNG specification. + + - __::png::addComment__ *file* *keyword* *lang* *keyword2* *text* + + Adds a unicode (international) comment to the PNG image in *file*, just + before the first data chunk. Will throw an error if no data chunk is found. + *keyword* has to be less than 80 characters long to conform to the PNG + specification. *keyword2* is the translated *keyword*, in the language + specified by the language identifier *lang*. + + - __::png::getPixelDimension__ *file* + + Returns a dictionary with keys __ppux__, __ppuy__ and __unit__ if the + information is present. Otherwise, it returns the empty string. + + The values of __ppux__ and __ppuy__ return the pixel per unit value in X or + Y direction. + + The allowed values for key __unit__ are __meter__ and __unknown__. In the + case of meter, the dpi value can be calculated by multiplying with the + conversion factor __0.0254__. + + - __::png::image__ *file* + + Given a PNG file returns the image in the list of scanlines format used by + Tk_GetColor. + + - __::png::write__ *file* *data* + + Takes a list of scanlines in the Tk_GetColor format and writes the + represented image to *file*. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *png* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[comment](../../../../index.md#comment), [image](../../../../index.md#image), +[png](../../../../index.md#png), [timestamp](../../../../index.md#timestamp) + +# CATEGORY + +File formats + +# COPYRIGHT + +Copyright © 2004, Code: Aaron Faupell +Copyright © 2004, Doc: Andreas Kupries ADDED embedded/md/tcllib/files/modules/pop3/pop3.md Index: embedded/md/tcllib/files/modules/pop3/pop3.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pop3/pop3.md @@ -0,0 +1,294 @@ + +[//000000001]: # (pop3 - Tcl POP3 Client Library) +[//000000002]: # (Generated from file 'pop3.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pop3(n) 1.9 tcllib "Tcl POP3 Client Library") + +# NAME + +pop3 - Tcl client for POP3 email protocol + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [TLS Security Considerations](#section2) + + - [API](#section3) + + - [Secure mail transfer](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.4 +package require pop3 ?1.9? + +[__::pop3::open__ ?__-msex__ 0|1? ?__-retr-mode__ retr|list|slow? ?__-socketcmd__ cmdprefix? ?__-stls__ 0|1? ?__-tls-callback__ stls-callback-command? *host username password* ?*port*?](#1) +[__::pop3::config__ *chan*](#2) +[__::pop3::status__ *chan*](#3) +[__::pop3::last__ *chan*](#4) +[__::pop3::retrieve__ *chan startIndex* ?*endIndex*?](#5) +[__::pop3::delete__ *chan startIndex* ?*endIndex*?](#6) +[__::pop3::list__ *chan* ?*msg*?](#7) +[__::pop3::top__ *chan* *msg* *n*](#8) +[__::pop3::uidl__ *chan* ?*msg*?](#9) +[__::pop3::capa__ *chan*](#10) +[__::pop3::close__ *chan*](#11) + +# DESCRIPTION + +The __pop3__ package provides a simple Tcl-only client library for the POP3 +email protocol as specified in [RFC +1939](http://www.rfc-editor.org/rfc/rfc1939.txt). It works by opening the +standard POP3 socket on the server, transmitting the username and password, then +providing a Tcl API to access the POP3 protocol commands. All server errors are +returned as Tcl errors (thrown) which must be caught with the Tcl __catch__ +command. + +# TLS Security Considerations + +This package uses the __[TLS](../../../../index.md#tls)__ package to handle the +security for __https__ urls and other socket connections. + +Policy decisions like the set of protocols to support and what ciphers to use +are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this +package itself however. Such decisions are the responsibility of whichever +application is using the package, and are likely influenced by the set of +servers the application will talk to as well. + +For example, in light of the recent [POODLE +attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html) +discovered by Google many servers will disable support for the SSLv3 protocol. +To handle this change the applications using __[TLS](../../../../index.md#tls)__ +must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__ +itself. Such a patch may be as simple as generally activating __tls1__ support, +as shown in the example below. + + package require tls + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol + + ... your own application code ... + +# API + + - __::pop3::open__ ?__-msex__ 0|1? ?__-retr-mode__ retr|list|slow? ?__-socketcmd__ cmdprefix? ?__-stls__ 0|1? ?__-tls-callback__ stls-callback-command? *host username password* ?*port*? + + Open a socket connection to the server specified by *host*, transmit the + *username* and *password* as login information to the server. The default + port number is __110__, which can be overridden using the optional *port* + argument. The return value is a channel used by all of the other ::pop3 + functions. + + The command recognizes three options + + * __-msex__ boolean + + Setting this option tells the package that the server we are talking to + is an MS Exchange server (which has some oddities we have to work + around). The default is __False__. + + * __-retr-mode__ retr|list|slow + + The retrieval mode determines how exactly messages are read from the + server. The allowed values are __retr__, __list__ and __slow__. The + default is __retr__. See __::pop3::retrieve__ for more information. + + * __-socketcmd__ cmdprefix + + This option allows the user to overide the use of the builtin + __[socket](../../../../index.md#socket)__ command with any + API-compatible command. The envisioned main use is the securing of the + new connection via SSL, through the specification of the command + __tls::socket__. This command is specially recognized as well, changing + the default port of the connection to __995__. + + * __-stls__ boolean + + Setting this option tells the package to secure the connection using SSL + or TLS. It performs STARTTLS as described in IETF RFC 2595, it first + opens a normal, unencrypted connection and then negotiates a SSLv3 or + TLSv1 connection. If the connection cannot be secured, the connection + will be closed and an error will be returned + + * __-tls-callback__ stls-callback-command + + This option allows the user to overide the __tls::callback__ used during + the __-stls__ SSL/TLS handshake. See the TLS manual for details on how + to implement this callback. + + - __::pop3::config__ *chan* + + Returns the configuration of the pop3 connection identified by the channel + handle *chan* as a serialized array. + + - __::pop3::status__ *chan* + + Query the server for the status of the mail spool. The status is returned as + a list containing two elements, the first is the number of email messages on + the server and the second is the size (in octets, 8 bit blocks) of the + entire mail spool. + + - __::pop3::last__ *chan* + + Query the server for the last email message read from the spool. This value + includes all messages read from all clients connecting to the login account. + This command may not be supported by the email server, in which case the + server may return 0 or an error. + + - __::pop3::retrieve__ *chan startIndex* ?*endIndex*? + + Retrieve a range of messages from the server. If the *endIndex* is not + specified, only one message will be retrieved. The return value is a list + containing each message as a separate element. See the *startIndex* and + *endIndex* descriptions below. + + The retrieval mode determines how exactly messages are read from the server. + The mode __retr__ assumes that the RETR command delivers the size of the + message as part of the command status and uses this to read the message + efficiently. In mode __list__ RETR does not deliver the size, but the LIST + command does and we use this to retrieve the message size before the actual + retrieval, which can then be done efficiently. In the last mode, __slow__, + the system is unable to obtain the size of the message to retrieve in any + manner and falls back to reading the message from the server line by line. + + It should also be noted that the system checks upon the configured mode and + falls back to the slower modes if the above assumptions are not true. + + - __::pop3::delete__ *chan startIndex* ?*endIndex*? + + Delete a range of messages from the server. If the *endIndex* is not + specified, only one message will be deleted. Note, the indices are not + reordered on the server, so if you delete message 1, then the first message + in the queue is message 2 (message index 1 is no longer valid). See the + *startIndex* and *endIndex* descriptions below. + + * *startIndex* + + The *startIndex* may be an index of a specific message starting with the + index 1, or it have any of the following values: + + + __start__ + + This is a logical value for the first message in the spool, + equivalent to the value 1. + + + __next__ + + The message immediately following the last message read, see + __::pop3::last__. + + + __end__ + + The most recent message in the spool (the end of the spool). This is + useful to retrieve only the most recent message. + + * *endIndex* + + The *endIndex* is an optional parameter and defaults to the value "-1", + which indicates to only retrieve the one message specified by + *startIndex*. If specified, it may be an index of a specific message + starting with the index "1", or it may have any of the following values: + + + __last__ + + The message is the last message read by a POP3 client, see + __::pop3::last__. + + + __end__ + + The most recent message in the spool (the end of the spool). + + - __::pop3::list__ *chan* ?*msg*? + + Returns the scan listing of the mailbox. If parameter *msg* is given, then + the listing only for that message is returned. + + - __::pop3::top__ *chan* *msg* *n* + + Optional POP3 command, not all servers may support this. __::pop3::top__ + retrieves headers of a message, specified by parameter *msg*, and number of + *n* lines from the message body. + + - __::pop3::uidl__ *chan* ?*msg*? + + Optional POP3 command, not all servers may support this. __::pop3::uidl__ + returns the uid listing of the mailbox. If the parameter *msg* is specified, + then the listing only for that message is returned. + + - __::pop3::capa__ *chan* + + Optional POP3 command, not all servers may support this. __::pop3::capa__ + returns a list of the capabilities of the server. TOP, SASL, UIDL, + LOGIN-DELAY and STLS are typical capabilities. See IETF RFC 2449. + + - __::pop3::close__ *chan* + + Gracefully close the connect after sending a POP3 QUIT command down the + socket. + +# Secure mail transfer + +A pop3 connection can be secured with SSL/TLS by requiring the package +__[TLS](../../../../index.md#tls)__ and then using either the option +__-socketcmd__ or the option __-stls__ of the command __pop3::open__. The first +method, option __-socketcmd__, will force the use of the __tls::socket__ command +when opening the connection. This is suitable for POP3 servers which expect SSL +connections only. These will generally be listening on port 995. + + package require tls + tls::init -cafile /path/to/ca/cert -keyfile ... + + # Create secured pop3 channel + pop3::open -socketcmd tls::socket \\ + $thehost $theuser $thepassword + + ... + +The second method, option __-stls__, will connect to the standard POP3 port and +then perform an STARTTLS handshake. This will only work for POP3 servers which +have this capability. The package will confirm that the server supports STARTTLS +and the handshake was performed correctly before proceeding with authentication. + + package require tls + tls::init -cafile /path/to/ca/cert -keyfile ... + + # Create secured pop3 channel + pop3::open -stls 1 \\ + $thehost $theuser $thepassword + + ... + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pop3* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[email](../../../../index.md#email), [mail](../../../../index.md#mail), +[pop](../../../../index.md#pop), [pop3](../../../../index.md#pop3), [rfc +1939](../../../../index.md#rfc_1939), [secure](../../../../index.md#secure), +[ssl](../../../../index.md#ssl), [tls](../../../../index.md#tls) + +# CATEGORY + +Networking ADDED embedded/md/tcllib/files/modules/pop3d/pop3d.md Index: embedded/md/tcllib/files/modules/pop3d/pop3d.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pop3d/pop3d.md @@ -0,0 +1,296 @@ + +[//000000001]: # (pop3d - Tcl POP3 Server Package) +[//000000002]: # (Generated from file 'pop3d.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pop3d(n) 1.1.0 tcllib "Tcl POP3 Server Package") + +# NAME + +pop3d - Tcl POP3 server implementation + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Options](#section2) + + - [Authentication](#section3) + + - [Mailboxes](#section4) + + - [Secure mail transfer](#section5) + + - [References](#section6) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.3 +package require pop3d ?1.1.0? + +[__::pop3d::new__ ?*serverName*?](#1) +[__serverName__ *option* ?*arg arg ...*?](#2) +[*serverName* __up__](#3) +[*serverName* __down__](#4) +[*serverName* __destroy__ ?*mode*?](#5) +[*serverName* __configure__](#6) +[*serverName* __configure__ *-option*](#7) +[*serverName* __configure__ *-option value*...](#8) +[*serverName* __cget__ *-option*](#9) +[*serverName* __conn__ list](#10) +[*serverName* __conn__ state *id*](#11) +[*authCmd* __exists__ *name*](#12) +[*authCmd* __lookup__ *name*](#13) +[*storageCmd* __dele__ *mbox* *msgList*](#14) +[*storageCmd* __lock__ *mbox*](#15) +[*storageCmd* __unlock__ *mbox*](#16) +[*storageCmd* __size__ *mbox* ?*msgId*?](#17) +[*storageCmd* __stat__ *mbox*](#18) +[*storageCmd* __get__ *mbox* *msgId*](#19) + +# DESCRIPTION + + - __::pop3d::new__ ?*serverName*? + + This command creates a new server object with an associated global Tcl + command whose name is *serverName*. + +The command __serverName__ may be used to invoke various operations on the +server. It has the following general form: + + - __serverName__ *option* ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. + +A pop3 server can be started on any port the caller has permission for from the +operating system. The default port will be 110, which is the port defined by the +standard specified in RFC 1939 +([http://www.rfc-editor.org/rfc/rfc1939.txt](http://www.rfc-editor.org/rfc/rfc1939.txt)). +After creating, configuring and starting a the server object will listen for and +accept connections on that port and handle them according to the POP3 protocol. + +*Note:* The server provided by this module will handle only the basic protocol +by itself. For the higher levels of user authentication and handling of the +actual mailbox contents callbacks will be invoked. + +The following commands are possible for server objects: + + - *serverName* __up__ + + After this call the server will listen for connections on its configured + port. + + - *serverName* __down__ + + After this call the server will stop listening for connections. This does + not affect existing connections. + + - *serverName* __destroy__ ?*mode*? + + Destroys the server object. Currently open connections are handled depending + on the chosen mode. The provided *mode*s are: + + * __kill__ + + Destroys the server immediately, and forcefully closes all currently + open connections. This is the default mode. + + * __defer__ + + Stops the server from accepting new connections and will actually + destroy it only after the last of the currently open connections for the + server is closed. + + - *serverName* __configure__ + + Returns a list containing all options and their current values in a format + suitable for use by the command __array set__. The options themselves are + described in section [Options](#section2). + + - *serverName* __configure__ *-option* + + Returns the current value of the specified option. This is an alias for the + method __cget__. The options themselves are described in section + [Options](#section2). + + - *serverName* __configure__ *-option value*... + + Sets the specified option to the provided value. The options themselves are + described in section [Options](#section2). + + - *serverName* __cget__ *-option* + + Returns the current value of the specified option. The options themselves + are described in section [Options](#section2). + + - *serverName* __conn__ list + + Returns a list containing the ids of all connections currently open. + + - *serverName* __conn__ state *id* + + Returns a list suitable for [__array set__] containing the state of the + connection referenced by *id*. + +# Options + +The following options are available to pop3 server objects. + + - __-port__ *port* + + Defines the *port* to listen on for new connections. Default is 110. This + option is a bit special. If *port* is set to "0" the server, or rather the + operating system, will select a free port on its own. When querying + __-port__ the id of this chosen port will be returned. Changing the port + while the server is up will neither change the returned value, nor will it + change on which port the server is listening on. Only after resetting the + server via a call to __down__ followed by a call to __up__ will the new port + take effect. It is at that time that the value returned when querying + __-port__ will change too. + + - __-auth__ *command* + + Defines a *command* prefix to call whenever the authentication of a user is + required. If no such command is specified the server will reject all users. + The interface which has to be provided by the command prefix is described in + section [Authentication](#section3). + + - __-storage__ *command* + + Defines a *command* prefix to call whenever the handling of mailbox contents + is required. If no such command is specified the server will claim that all + mailboxes are empty. The interface which has to be provided by the command + prefix is described in section [Mailboxes](#section4). + + - __-socket__ *command* + + Defines a *command* prefix to call for opening the listening socket. This + can be used to make the pop3 server listen on a SSL socket as provided by + the __[tls](../../../../index.md#tls)__ package, see the command + __tls::socket__. + +# Authentication + +Here we describe the interface which has to be provided by the authentication +callback so that pop3 servers following the interface of this module are able to +use it. + + - *authCmd* __exists__ *name* + + This method is given a user*name* and has to return a boolean value telling + whether or not the specified user exists. + + - *authCmd* __lookup__ *name* + + This method is given a user*name* and has to return a two-element list + containing the password for this user and a storage reference, in this + order. + + The storage reference is passed unchanged to the storage callback, see + sections [Options](#section2) and [Mailboxes](#section4) for either the + option defining it and or the interface to provide, respectively. + +# Mailboxes + +Here we describe the interface which has to be provided by the storage callback +so that pop3 servers following the interface of this module are able to use it. +The *mbox* argument is the storage reference as returned by the __lookup__ +method of the authentication command, see section [Authentication](#section3). + + - *storageCmd* __dele__ *mbox* *msgList* + + Deletes the messages whose numeric ids are contained in the *msgList* from + the mailbox specified via *mbox*. + + - *storageCmd* __lock__ *mbox* + + This method locks the specified mailbox for use by a single connection to + the server. This is necessary to prevent havoc if several connections to the + same mailbox are open. The complementary method is __unlock__. The command + will return true if the lock could be set successfully or false if not. + + - *storageCmd* __unlock__ *mbox* + + This is the complementary method to __lock__, it revokes the lock on the + specified mailbox. + + - *storageCmd* __size__ *mbox* ?*msgId*? + + Determines the size of the message specified through its id in *msgId*, in + bytes, and returns this number. The command will return the size of the + whole maildrop if no message id was specified. + + - *storageCmd* __stat__ *mbox* + + Determines the number of messages in the specified mailbox and returns this + number. + + - *storageCmd* __get__ *mbox* *msgId* + + Returns a handle for the specified message. This handle is a mime token + following the interface described in the documentation of package + __[mime](../mime/mime.md)__. The pop3 server will use the functionality of + the mime token to send the mail to the requestor at the other end of a pop3 + connection. + +# Secure mail transfer + +The option __-socket__ (see [Options](#section2)) enables users of the package +to override how the server opens its listening socket. The envisioned main use +is the specification of the __tls::socket__ command, see package +__[tls](../../../../index.md#tls)__, to secure the communication. + + package require tls + tls::init \\ + ... + + pop3d::new S -socket tls::socket + ... + +# References + + 1. [RFC 1939](http://www.rfc-editor.org/rfc/rfc1939.txt) + + 1. [RFC 2449](http://www.rfc-editor.org/rfc/rfc2449.txt) + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pop3d* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[internet](../../../../index.md#internet), +[network](../../../../index.md#network), [pop3](../../../../index.md#pop3), +[protocol](../../../../index.md#protocol), [rfc +1939](../../../../index.md#rfc_1939), [secure](../../../../index.md#secure), +[ssl](../../../../index.md#ssl), [tls](../../../../index.md#tls) + +# CATEGORY + +Networking + +# COPYRIGHT + +Copyright © 2002-2009 Andreas Kupries +Copyright © 2005 Reinhard Max ADDED embedded/md/tcllib/files/modules/pop3d/pop3d_dbox.md Index: embedded/md/tcllib/files/modules/pop3d/pop3d_dbox.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pop3d/pop3d_dbox.md @@ -0,0 +1,190 @@ + +[//000000001]: # (pop3d::dbox - Tcl POP3 Server Package) +[//000000002]: # (Generated from file 'pop3d_dbox.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pop3d::dbox(n) 1.0.2 tcllib "Tcl POP3 Server Package") + +# NAME + +pop3d::dbox - Simple mailbox database for pop3d + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.3 +package require pop3d::dbox ?1.0.2? + +[__::pop3d::dbox::new__ ?*dbName*?](#1) +[__dbName__ *option* ?*arg arg ...*?](#2) +[*dbName* __destroy__](#3) +[*dbName* __base__ *base*](#4) +[*dbName* __add__ *mbox*](#5) +[*dbName* __remove__ *mbox*](#6) +[*dbName* __move__ *old new*](#7) +[*dbName* __list__](#8) +[*dbName* __exists__ *mbox*](#9) +[*dbName* __locked__ *mbox*](#10) +[*dbName* __lock__ *mbox*](#11) +[*dbName* __unlock__ *mbox*](#12) +[*dbName* __stat__ *mbox*](#13) +[*dbName* __size__ *mbox* ?*msgId*?](#14) +[*dbName* __dele__ *mbox msgList*](#15) +[*storageCmd* __get__ *mbox* *msgId*](#16) + +# DESCRIPTION + +The package __pop3d::dbox__ provides simple/basic mailbox management facilities. +Each mailbox object manages a single base directory whose subdirectories +represent the managed mailboxes. Mails in a mailbox are represented by files in +a mailbox directory, where each of these files contains a single mail, both +headers and body, in RFC 822 +([http://www.rfc-editor.org/rfc/rfc822.txt](http://www.rfc-editor.org/rfc/rfc822.txt)) +conformant format. + +Any mailbox object following the interface described below can be used in +conjunction with the pop3 server core provided by the package +__[pop3d](pop3d.md)__. It is especially possible to directly use the objects +created by this package in the storage callback of pop3 servers following the +same interface as servers created by the package __[pop3d](pop3d.md)__. + + - __::pop3d::dbox::new__ ?*dbName*? + + This command creates a new database object with an associated global Tcl + command whose name is *dbName*. + +The command __dbName__ may be used to invoke various operations on the database. +It has the following general form: + + - __dbName__ *option* ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. + +The following commands are possible for database objects: + + - *dbName* __destroy__ + + Destroys the mailbox database and all transient data. The directory + associated with the object is not destroyed. + + - *dbName* __base__ *base* + + Defines the base directory containing the mailboxes to manage. If this + method is not called none of the following methods will work. + + - *dbName* __add__ *mbox* + + Adds a mailbox of name *mbox* to the database. The name must be a valid path + component. + + - *dbName* __remove__ *mbox* + + Removes the mailbox specified through *mbox*, and the mails contained + therein, from the database. This method will fail if the specified mailbox + is locked. + + - *dbName* __move__ *old new* + + Changes the name of the mailbox *old* to *new*. + + - *dbName* __list__ + + Returns a list containing the names of all mailboxes in the directory + associated with the database. + + - *dbName* __exists__ *mbox* + + Returns true if the mailbox with name *mbox* exists in the database, or + false if not. + + - *dbName* __locked__ *mbox* + + Checks if the mailbox specified through *mbox* is currently locked. + + - *dbName* __lock__ *mbox* + + This method locks the specified mailbox for use by a single connection to + the server. This is necessary to prevent havoc if several connections to the + same mailbox are open. The complementary method is __unlock__. The command + will return true if the lock could be set successfully or false if not. + + - *dbName* __unlock__ *mbox* + + This is the complementary method to __lock__, it revokes the lock on the + specified mailbox. + + - *dbName* __stat__ *mbox* + + Determines the number of messages in the specified mailbox and returns this + number. This method fails if the mailbox *mbox* is not locked. + + - *dbName* __size__ *mbox* ?*msgId*? + + Determines the size of the message specified through its id in *msgId*, in + bytes, and returns this number. The command will return the size of the + whole maildrop if no message id was specified. If specified the *msgId* has + to be in the range "1 ... [*dbName* __stat__]" or this call will fail. If + __stat__ was not called before this call, __size__ will assume that there + are zero messages in the mailbox. + + - *dbName* __dele__ *mbox msgList* + + Deletes the messages whose numeric ids are contained in the *msgList* from + the mailbox specified via *mbox*. The *msgList* must not be empty or this + call will fail. The numeric ids in *msgList* have to be in the range "1 ... + [*dbName* __stat__]" or this call will fail. If __stat__ was not called + before this call, __dele__ will assume that there are zero messages in the + mailbox. + + - *storageCmd* __get__ *mbox* *msgId* + + Returns a handle for the specified message. This handle is a mime token + following the interface described in the documentation of package + __[mime](../mime/mime.md)__. The token is *read-only*. In other words, the + caller is allowed to do anything with the token except to modify it. The + *msgId* has to be in the range "1 ... [*dbName* __stat__]" or this call will + fail. If __stat__ was not called before this call, __get__ will assume that + there are zero messages in the mailbox. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pop3d* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[internet](../../../../index.md#internet), +[network](../../../../index.md#network), [pop3](../../../../index.md#pop3), +[protocol](../../../../index.md#protocol), [rfc +822](../../../../index.md#rfc_822) + +# CATEGORY + +Networking + +# COPYRIGHT + +Copyright © 2002 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pop3d/pop3d_udb.md Index: embedded/md/tcllib/files/modules/pop3d/pop3d_udb.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pop3d/pop3d_udb.md @@ -0,0 +1,144 @@ + +[//000000001]: # (pop3d::udb - Tcl POP3 Server Package) +[//000000002]: # (Generated from file 'pop3d_udb.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pop3d::udb(n) 1.0.1 tcllib "Tcl POP3 Server Package") + +# NAME + +pop3d::udb - Simple user database for pop3d + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require pop3d::udb ?1.0.1? + +[__::pop3d::udb::new__ ?*dbName*?](#1) +[__dbName__ *option* ?*arg arg ...*?](#2) +[*dbName* __destroy__](#3) +[*dbName* __add__ *user pwd storage*](#4) +[*dbName* __remove__ *user*](#5) +[*dbName* __rename__ *user newName*](#6) +[*dbName* __lookup__ *user*](#7) +[*dbName* __exists__ *user*](#8) +[*dbName* __who__](#9) +[*dbName* __save__ ?*file*?](#10) +[*dbName* __read__ *file*](#11) + +# DESCRIPTION + +The package __pop3d::udb__ provides simple in memory databases which can be used +in conjunction with the pop3 server core provided by the package +__[pop3d](pop3d.md)__. The databases will use the names of users as keys and +associates passwords and storage references with them. + +Objects created by this package can be directly used in the authentication +callback of pop3 servers following the same interface as servers created by the +package __[pop3d](pop3d.md)__. + + - __::pop3d::udb::new__ ?*dbName*? + + This command creates a new database object with an associated global Tcl + command whose name is *dbName*. + +The command __dbName__ may be used to invoke various operations on the database. +It has the following general form: + + - __dbName__ *option* ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. + +The following commands are possible for database objects: + + - *dbName* __destroy__ + + Destroys the database object. + + - *dbName* __add__ *user pwd storage* + + Add a new user or changes the data of an existing user. Stores *password* + and *storage* reference for the given *user*. + + - *dbName* __remove__ *user* + + Removes the specified *user* from the database. + + - *dbName* __rename__ *user newName* + + Changes the name of the specified *user* to *newName*. + + - *dbName* __lookup__ *user* + + Searches the database for the specified *user* and returns a two-element + list containing the associated password and storage reference, in this + order. Throws an error if the user could not be found. This is the interface + as expected by the authentication callback of package __[pop3d](pop3d.md)__. + + - *dbName* __exists__ *user* + + Returns true if the specified *user* is known to the database, else false. + + - *dbName* __who__ + + Returns a list of users known to the database. + + - *dbName* __save__ ?*file*? + + Saves the contents of the database into the given *file*. If the file is not + specified the system will use the path last used in a call to *dbName* + __read__. The generated file can be read by the __read__ method. + + - *dbName* __read__ *file* + + Reads the specified *file* and adds the contained user definitions to the + database. As the file is actually + __[source](../../../../index.md#source)__'d a safe interpreter is employed + to safeguard against malicious code. This interpreter knows the __add__ + command for adding users and their associated data to this database. This + command has the same argument signature as the method __add__. The path of + the *file* is remembered internally so that it can be used in the next call + of *dbName* __save__ without an argument. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pop3d* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[internet](../../../../index.md#internet), +[network](../../../../index.md#network), [pop3](../../../../index.md#pop3), +[protocol](../../../../index.md#protocol) + +# CATEGORY + +Networking + +# COPYRIGHT + +Copyright © 2002 Andreas Kupries ADDED embedded/md/tcllib/files/modules/practcl/practcl.md Index: embedded/md/tcllib/files/modules/practcl/practcl.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/practcl/practcl.md @@ -0,0 +1,118 @@ + +[//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]: # (practcl(n) 0.11 tcllib "The The Proper Rational API for C to Tool Command Language Module") + +# NAME + +practcl - The Practcl Module + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require 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) + +# DESCRIPTION + +The Practcl module is a tool for integrating large modules for C API Tcl code +that requires custom Tcl types and TclOO objects. + +# COMMANDS + + - __CPUTS__ *varname* *body* ?*body*...? + + Appends blocks of text to a buffer. This command tries to reduce the number + of line breaks between bodies. + + - __practcl::_isdirectory__ *path* + + Returns true if *path* is a directory, using the test + + - __practcl::object__ *parent* ?*keyvaluelist*? + + A generic Practcl object + + - __practcl::library__ ?*keyvaluelist*? + + A Practcl object representing a library container + + - __practcl::exe__ ?*keyvaluelist*? + + A Practcl object representing a wrapped executable + + - __practcl::product__ *parent* ?*keyvaluelist*? + + A Practcl object representing a compiled product + + - __practcl::cheader__ *parent* ?*keyvaluelist*? + + A Practcl object representing an externally generated c header + + - __practcl::csource__ *parent* ?*keyvaluelist*? + + A Practcl object representing an externally generated c source file + + - __practcl::module__ *parent* ?*keyvaluelist*? + + A Practcl object representing a dynamically generated C/H/Tcl suite + + - __practcl::submodule__ *parent* ?*keyvaluelist*? + + A Practcl object representing a dynamically generated C/H/Tcl suite, + subordinate to a module + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *practcl* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[practcl](../../../../index.md#practcl) + +# CATEGORY + +TclOO + +# COPYRIGHT + +Copyright © 2016-2018 Sean Woods ADDED embedded/md/tcllib/files/modules/processman/processman.md Index: embedded/md/tcllib/files/modules/processman/processman.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/processman/processman.md @@ -0,0 +1,124 @@ + +[//000000001]: # (processman - processman) +[//000000002]: # (Generated from file 'processman.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (processman(n) 0.1 tcllib "processman") + +# NAME + +processman - Tool for automating the period callback of commands + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Commands](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require twapi 3.1 +package require cron 1.1 +package require processman ?0.1? + +[__::processman::find_exe__ *name*](#1) +[__::processman::kill__ *id*](#2) +[__::processman::kill_all__](#3) +[__::processman::killexe__ *name*](#4) +[__::processman::onexit__ *id* *cmd*](#5) +[__::processman::priority__ *id* *level*](#6) +[__::processman::process_list__](#7) +[__::processman::process_list__ *id*](#8) +[__::processman::spawn__ *id* *cmd* *args*](#9) + +# DESCRIPTION + +The __processman__ package provides a Pure-tcl set of utilities to manage child +processes in a platform-generic nature. + +# Commands + + - __::processman::find_exe__ *name* + + Locate an executable by the name of *name* in the system path. On windows, + also add the .exe extention if not given. + + - __::processman::kill__ *id* + + Kill a child process *id*. + + - __::processman::kill_all__ + + Kill all processes spawned by this program + + - __::processman::killexe__ *name* + + Kill a process identified by the executable. On Unix, this triggers a + killall. On windows, __twapi::get_process_ids__ is used to map a name one or + more IDs, which are then killed. + + - __::processman::onexit__ *id* *cmd* + + Arrange to execute the script *cmd* when this programe detects that process + *id* as terminated. + + - __::processman::priority__ *id* *level* + + Mark process *id* with the priorty *level*. Valid levels: low, high, + default. + + On Unix, the process is tagged using the __nice__ command. + + On Windows, the process is modifed via the __twapi::set_priority_class__ + + - __::processman::process_list__ + + Return a list of processes that have been triggered by this program, as well + as a boolean flag to indicate if the process is still running. + + - __::processman::process_list__ *id* + + Return true if process *id* is still running, false otherwise. + + - __::processman::spawn__ *id* *cmd* *args* + + Start a child process, identified by *id*. *cmd* is the name of the command + to execute. *args* are arguments to pass to that command. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *odie* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[odie](../../../../index.md#odie), [processman](../../../../index.md#processman) + +# CATEGORY + +System + +# COPYRIGHT + +Copyright © 2015 Sean Woods ADDED embedded/md/tcllib/files/modules/profiler/profiler.md Index: embedded/md/tcllib/files/modules/profiler/profiler.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/profiler/profiler.md @@ -0,0 +1,148 @@ + +[//000000001]: # (profiler - Tcl Profiler) +[//000000002]: # (Generated from file 'profiler.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (profiler(n) 0.3 tcllib "Tcl Profiler") + +# NAME + +profiler - Tcl source code profiler + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.3 +package require profiler ?0.3? + +[__::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) + +# DESCRIPTION + +The __profiler__ package provides a simple Tcl source code profiler. It is a +function-level profiler; that is, it collects only function-level information, +not the more detailed line-level information. It operates by redefining the Tcl +__[proc](../../../../index.md#proc)__ command. Profiling is initiated via the +__::profiler::init__ command. + +# COMMANDS + + - __::profiler::init__ + + Initiate profiling. All procedures created after this command is called will + be profiled. To profile an entire application, this command must be called + before any other commands. + + - __::profiler::dump__ *pattern* + + Dump profiling information for the all functions matching *pattern*. If no + pattern is specified, information for all functions will be returned. The + result is a list of key/value pairs that maps function names to information + about that function. The information about each function is in turn a list + of key/value pairs. The keys used and their values are: + + * __totalCalls__ + + The total number of times *functionName* was called. + + * __callerDist__ + + A list of key/value pairs mapping each calling function that called + *functionName* to the number of times it called *functionName*. + + * __compileTime__ + + The runtime, in clock clicks, of *functionName* the first time that it + was called. + + * __totalRuntime__ + + The sum of the runtimes of all calls of *functionName*. + + * __averageRuntime__ + + Average runtime of *functionName*. + + * __descendantTime__ + + Sum of the time spent in descendants of *functionName*. + + * __averageDescendantTime__ + + Average time spent in descendants of *functionName*. + + - __::profiler::print__ ?*pattern*? + + Print profiling information for all functions matching *pattern*. If no + pattern is specified, information about all functions will be displayed. The + return result is a human readable display of the profiling information. + + - __::profiler::reset__ ?*pattern*? + + Reset profiling information for all functions matching *pattern*. If no + pattern is specified, information will be reset for all functions. + + - __::profiler::suspend__ ?*pattern*? + + Suspend profiling for all functions matching *pattern*. If no pattern is + specified, profiling will be suspended for all functions. It stops gathering + profiling information after this command is issued. However, it does not + erase any profiling information that has been gathered previously. Use + resume command to re-enable profiling. + + - __::profiler::resume__ ?*pattern*? + + Resume profiling for all functions matching *pattern*. If no pattern is + specified, profiling will be resumed for all functions. This command should + be invoked after suspending the profiler in the code. + + - __::profiler::sortFunctions__ *key* + + Return a list of functions sorted by a particular profiling statistic. + Supported values for *key* are: __calls__, __exclusiveTime__, + __compileTime__, __nonCompileTime__, __totalRuntime__, __avgExclusiveTime__, + and __avgRuntime__. The return result is a list of lists, where each sublist + consists of a function name and the value of *key* for that function. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *profiler* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[performance](../../../../index.md#performance), +[profile](../../../../index.md#profile), [speed](../../../../index.md#speed) + +# CATEGORY + +Programming tools ADDED embedded/md/tcllib/files/modules/pt/pt_astree.md Index: embedded/md/tcllib/files/modules/pt/pt_astree.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_astree.md @@ -0,0 +1,299 @@ + +[//000000001]: # (pt::ast - Parser Tools) +[//000000002]: # (Generated from file 'pt_astree.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::ast(n) 1.1 tcllib "Parser Tools") + +# NAME + +pt::ast - Abstract Syntax Tree Serialization + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [AST serialization format](#section3) + + - [Example](#subsection1) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::ast ?1.1? + +[__::pt::ast__ __verify__ *serial* ?*canonvar*?](#1) +[__::pt::ast__ __verify-as-canonical__ *serial*](#2) +[__::pt::ast__ __canonicalize__ *serial*](#3) +[__::pt::ast__ __print__ *serial*](#4) +[__::pt::ast__ __bottomup__ *cmdprefix* *ast*](#5) +[__cmdprefix__ *ast*](#6) +[__::pt::ast__ __topdown__ *cmdprefix* *pe*](#7) +[__::pt::ast__ __equal__ *seriala* *serialb*](#8) +[__::pt::ast__ __new0__ *s* *loc* ?*child*...?](#9) +[__::pt::ast__ __new__ *s* *start* *end* ?*child*...?](#10) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides commands to work with the serializations of abstract +syntax trees as managed by the Parser Tools, and specified in section [AST +serialization format](#section3). + +This is a supporting package in the Core Layer of Parser Tools. + +![](../../../../image/arch_core_support.png) + +# API + + - __::pt::ast__ __verify__ *serial* ?*canonvar*? + + This command verifies that the content of *serial* is a valid serialization + of an abstract syntax tree and will throw an error if that is not the case. + The result of the command is the empty string. + + If the argument *canonvar* is specified it is interpreted as the name of a + variable in the calling context. This variable will be written to if and + only if *serial* is a valid regular serialization. Its value will be a + boolean, with __True__ indicating that the serialization is not only valid, + but also *canonical*. __False__ will be written for a valid, but + non-canonical serialization. + + For the specification of serializations see the section [AST serialization + format](#section3). + + - __::pt::ast__ __verify-as-canonical__ *serial* + + This command verifies that the content of *serial* is a valid *canonical* + serialization of an abstract syntax tree and will throw an error if that is + not the case. The result of the command is the empty string. + + For the specification of canonical serializations see the section [AST + serialization format](#section3). + + - __::pt::ast__ __canonicalize__ *serial* + + This command assumes that the content of *serial* is a valid *regular* + serialization of an abstract syntax and will throw an error if that is not + the case. + + It will then convert the input into the *canonical* serialization of the + contained tree and return it as its result. If the input is already + canonical it will be returned unchanged. + + For the specification of regular and canonical serializations see the + section [AST serialization format](#section3). + + - __::pt::ast__ __print__ *serial* + + This command assumes that the argument *serial* contains a valid + serialization of an abstract syntax tree and returns a string containing + that tree in a human readable form. + + The exact format of this form is not specified and cannot be relied on for + parsing or other machine-based activities. + + For the specification of serializations see the section [AST serialization + format](#section3). + + - __::pt::ast__ __bottomup__ *cmdprefix* *ast* + + This command walks the abstract syntax tree *ast* from the bottom up to the + root, invoking the command prefix *cmdprefix* for each node. This implies + that the children of a node N are handled before N. + + The command prefix has the signature + + * __cmdprefix__ *ast* + + I.e. it is invoked with the ast node the walk is currently at. + + The result returned by the command prefix replaces *ast* in the node it + was a child of, allowing transformations of the tree. + + This also means that for all inner node the contents of the children + elements are the results of the command prefix invoked for the children + of this node. + + - __::pt::ast__ __topdown__ *cmdprefix* *pe* + + This command walks the abstract syntax tree *ast* from the root down to the + leaves, invoking the command prefix *cmdprefix* for each node. This implies + that the children of a node N are handled after N. + + The command prefix has the same signature as for __bottomup__, see above. + + The result returned by the command prefix is *ignored*. + + - __::pt::ast__ __equal__ *seriala* *serialb* + + This command tests the two sbstract syntax trees *seriala* and *serialb* for + structural equality. The result of the command is a boolean value. It will + be set to __true__ if the trees are identical, and __false__ otherwise. + + String equality is usable only if we can assume that the two trees are pure + Tcl lists. + + - __::pt::ast__ __new0__ *s* *loc* ?*child*...? + + This command command constructs the ast for a nonterminal node refering + refering to the symbol *s* at position *loc* in the input, and the set of + child nodes *child* ..., from left right. The latter may be empty. The + constructed node is returned as the result of the command. The end position + is *loc*-1, i.e. one character before the start. This type of node is + possible for rules containing optional parts. + + - __::pt::ast__ __new__ *s* *start* *end* ?*child*...? + + This command command constructs the ast for a nonterminal node refering to + the symbol *s* covering the range of positions *start* to *end* in the + input, and the set of child nodes *child* ..., from left right. The latter + may be empty. The constructed node is returned as the result of the command. + +# AST serialization format + +Here we specify the format used by the Parser Tools to serialize Abstract Syntax +Trees (ASTs) as immutable values for transport, comparison, etc. + +Each node in an AST represents a nonterminal symbol of a grammar, and the range +of tokens/characters in the input covered by it. ASTs do not contain terminal +symbols, i.e. tokens/characters. These can be recovered from the input given a +symbol's location. + +We distinguish between *regular* and *canonical* serializations. While a tree +may have more than one regular serialization only exactly one of them will be +*canonical*. + + - Regular serialization + + The serialization of any AST is the serialization of its root node. + + The serialization of any node is a Tcl list containing at least three + elements. + + The first element is the name of the nonterminal symbol stored in the node. + + The second and third element are the locations of the first and last token + in the token stream the node represents (covers). + + Locations are provided as non-negative integer offsets from the beginning of + the token stream, with the first token found in the stream located at offset + 0 (zero). + + The end location has to be equal to or larger than the start location. + + All elements after the first three represent the children of the node, which + are themselves nodes. This means that the serializations of nodes without + children, i.e. leaf nodes, have exactly three elements. The children are + stored in the list with the leftmost child first, and the rightmost child + last. + + - Canonical serialization + + The canonical serialization of an abstract syntax tree has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this tree. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the parsing expression grammar below + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +and the input string + + 120+5 + +then a parser should deliver the abstract syntax tree below (except for +whitespace) + + set ast {Expression 0 4 + {Factor 0 4 + {Term 0 2 + {Number 0 2 + {Digit 0 0} + {Digit 1 1} + {Digit 2 2} + } + } + {AddOp 3 3} + {Term 4 4 + {Number 4 4 + {Digit 4 4} + } + } + } + } + +Or, more graphical + +![](../../../../image/expr_ast.png) + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_cparam_config_critcl.md Index: embedded/md/tcllib/files/modules/pt/pt_cparam_config_critcl.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_cparam_config_critcl.md @@ -0,0 +1,106 @@ + +[//000000001]: # (pt::cparam::configuration::critcl - Parser Tools) +[//000000002]: # (Generated from file 'pt_cparam_config_critcl.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::cparam::configuration::critcl(n) 1.0.2 tcllib "Parser Tools") + +# NAME + +pt::cparam::configuration::critcl - C/PARAM, Canned configuration, Critcl + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::cparam::configuration::critcl ?1.0.2? + +[__::pt::cparam::configuration::critcl__ __def__ *name* *pkg* *version* *cmdprefix*](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package is an adjunct to __[pt::peg::to::cparam](pt_peg_to_cparam.md)__, to +make the use of this highly configurable package easier by providing a canned +configuration. When applied this configuration causes the package +__[pt::peg::to::cparam](pt_peg_to_cparam.md)__ to generate __critcl__-based +parser packages. + +It is a supporting package in the Core Layer of Parser Tools. + +![](../../../../image/arch_core_support.png) + +# API + + - __::pt::cparam::configuration::critcl__ __def__ *name* *pkg* *version* *cmdprefix* + + The command applies the configuration provided by this package to the + *cmdprefix*, causing the creation of __critcl__-based parsers whose class is + *name*, in package *pkg* with *version*. + + The use of a command prefix as API allows application of the configuration + to not only __[pt::peg::to::cparam](pt_peg_to_cparam.md)__ + (__pt::peg::to::cparam configure__), but also export manager instances and + PEG containers (__$export configuration set__ and __[$container exporter] + configuration set__ respectively). + + Or anything other command prefix accepting two arguments, option and value. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_cparam_config_tea.md Index: embedded/md/tcllib/files/modules/pt/pt_cparam_config_tea.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_cparam_config_tea.md @@ -0,0 +1,106 @@ + +[//000000001]: # (pt::cparam::configuration::tea - Parser Tools) +[//000000002]: # (Generated from file 'pt_cparam_config_tea.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::cparam::configuration::tea(n) 0.1 tcllib "Parser Tools") + +# NAME + +pt::cparam::configuration::tea - C/PARAM, Canned configuration, TEA + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::cparam::configuration::tea ?0.1? + +[__::pt::cparam::configuration::tea__ __def__ *name* *pkg* *version* *cmdprefix*](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package is an adjunct to __[pt::peg::to::cparam](pt_peg_to_cparam.md)__, to +make the use of this highly configurable package easier by providing a canned +configuration. When applied this configuration causes the package +__[pt::peg::to::cparam](pt_peg_to_cparam.md)__ to generate plain parser code +ready for inclusion into a *TEA*-based C extension. + +It is a supporting package in the Core Layer of Parser Tools. + +![](../../../../image/arch_core_support.png) + +# API + + - __::pt::cparam::configuration::tea__ __def__ *name* *pkg* *version* *cmdprefix* + + The command applies the configuration provided by this package to the + *cmdprefix*, causing the creation of __tea__-based parsers whose class is + *name*, in package *pkg* with *version*. + + The use of a command prefix as API allows application of the configuration + to not only __[pt::peg::to::cparam](pt_peg_to_cparam.md)__ + (__pt::peg::to::cparam configure__), but also export manager instances and + PEG containers (__$export configuration set__ and __[$container exporter] + configuration set__ respectively). + + Or anything other command prefix accepting two arguments, option and value. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_from_api.md Index: embedded/md/tcllib/files/modules/pt/pt_from_api.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_from_api.md @@ -0,0 +1,490 @@ + +[//000000001]: # (pt_import_api - Parser Tools) +[//000000002]: # (Generated from file 'pt_from_api.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt_import_api(i) 1 tcllib "Parser Tools") + +# NAME + +pt_import_api - Parser Tools Import API + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Converter API](#section2) + + - [Plugin API](#section3) + + - [Usage](#section4) + + - [PEG serialization format](#section5) + + - [Example](#subsection1) + + - [PE serialization format](#section6) + + - [Example](#subsection2) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 + +[__CONVERTER__ __convert__ *text*](#1) +[__IncludeFile__ *currentfile* *path*](#2) +[__::import__ *text*](#3) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This document describes two APIs. First the API shared by all packages for the +conversion of some other format into Parsing Expression Grammars , and then the +API shared by the packages which implement the import plugins sitting on top of +the conversion packages. + +Its intended audience are people who wish to create their own converter for some +type of input, and/or an import plugin for their or some other converter. + +It resides in the Import section of the Core Layer of Parser Tools. + +![](../../../../image/arch_core_import.png) + +# Converter API + +Any (grammar) import converter has to follow the rules set out below: + + 1. A converter is a package. Its name is arbitrary, however it is recommended + to put it under the __::pt::peg::from__ namespace. + + 1. The package provides either a single Tcl command following the API outlined + below, or a class command whose instances follow the same API. The commands + which follow the API are called *converter commands*. + + 1. A converter command has to provide the following single method with the + given signature and semantic. Converter commands are allowed to provide + more methods of their own, but not less, and they may not provide different + semantics for the standardized method. + + - __CONVERTER__ __convert__ *text* + + This method has to accept some *text*, a parsing expression grammar in + some format. The result of the method has to be the canonical + serialization of a parsing expression grammar, as specified in section + [PEG serialization format](#section5), the result of reading and + converting the input text. + +# Plugin API + +Any (grammar) import plugin has to follow the rules set out below: + + 1. A plugin is a package. + + 1. The name of a plugin package has the form pt::peg::import::__FOO__, where + __FOO__ is the name of the format the plugin will accept input for. + + 1. The plugin can expect that the package __pt::peg::import::plugin__ is + present, as indicator that it was invoked from a genuine plugin manager. + + It is recommended that a plugin does check for the presence of this + package. + + 1. The plugin can expect that a command named __IncludeFile__ is present, with + the signature + + - __IncludeFile__ *currentfile* *path* + + This command has to be invoked by the plugin when it has to process an + included file, if the format has the concept of such. + + The plugin has to supply the following arguments + + * string *currentfile* + + The path of the file it is currently processing. This may be the + empty string if no such is known. + + * string *path* + + The path of the include file as specified in the include directive + being processed. + + The result of the command will be a 5-element list containing + + A boolean flag indicating the success (__True__) or failure (__False__) + of the operation. + + In case of success the contents of the included file, and the empty + string otherwise. + + The resolved, i.e. absolute path of the included file, if possible, or + the unchanged *path* argument. This is for display in an error message, + or as the *currentfile* argument of another call to __IncludeFile__ + should this file contain more files. + + In case of success an empty string, and for failure a code indicating + the reason for it, one of + + * notfound + + The specified file could not be found. + + * notread + + The specified file was found, but not be read into memory. + + An empty string in case of success of a __notfound__ failure, and an + additional error message describing the reason for a __notread__ error + in more detail. + + 1. A plugin has to provide a single command, in the global namespace, with the + signature shown below. Plugins are allowed to provide more commands of + their own, but not less, and they may not provide different semantics for + the standardized command. + + - __::import__ *text* + + This command has to accept the a text containing a parsing expression + grammar in some format. The result of the command has to be the result + of the converter invoked by the plugin for the input grammar, the + canonical serialization of the parsing expression grammar contained in + the input. + + * string *text* + + This argument will contain the parsing expression grammar for which + to generate the serialization. The specification of what a + *canonical* serialization is can be found in the section [PEG + serialization format](#section5). + + 1. A single usage cycle of a plugin consists of an invokation of the command + __[import](../../../../index.md#import)__. This call has to leave the + plugin in a state where another usage cycle can be run without problems. + +# Usage + +To use a converter do + + # Get the converter (single command here, not class) + package require the-converter-package + + # Perform the conversion + set serial [theconverter convert $thegrammartext] + + ... process the result ... + +To use a plugin __FOO__ do + + # Get an import plugin manager + package require pt::peg::import + pt::peg::import I + + # Run the plugin, and the converter inside. + set serial [I import serial $thegrammartext FOO] + + ... process the result ... + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section6). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section6). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_introduction.md Index: embedded/md/tcllib/files/modules/pt/pt_introduction.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_introduction.md @@ -0,0 +1,215 @@ + +[//000000001]: # (pt_introduction - Parser Tools) +[//000000002]: # (Generated from file 'pt_introduction.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt_introduction(n) 1 tcllib "Parser Tools") + +# NAME + +pt_introduction - Introduction to Parser Tools + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Parser Tools Architecture](#section2) + + - [User Packages](#subsection1) + + - [Core Packages](#subsection2) + + - [Support Packages](#subsection3) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 + +# DESCRIPTION + +Welcome to the Parser Tools, a system for the creation and manipulation of +parsers and the grammars driving them. + +What are your goals which drove you here ? + + 1. Do you simply wish to create a parser for some language ? + + In that case have a look at our parser generator application, + __[pt](../../apps/pt.md)__, or, for a slightly deeper access, the package + underneath it, __[pt::pgen](pt_pgen.md)__. + + 1. Do you wish to know more about the architecture of the system ? + + This is described in the section [Parser Tools Architecture](#section2), + below + + 1. Is your interest in the theoretical background upon which the packages and + tools are build ? + + See the *[Introduction to Parsing Expression + Grammars](pt_peg_introduction.md)*. + +# Parser Tools Architecture + +The system can be split into roughly three layers, as seen in the figure below + +![](../../../../image/architecture.png) These layers are, from high to low: + + 1. At the top we have the application and the packages using the packages of + the layer below to implement common usecases. One example is the + aforementioned __[pt::pgen](pt_pgen.md)__ which provides a parser + generator. + + The list of packages belonging to this layer can be found in section [User + Packages](#subsection1) + + 1. In this layer we have the packages which provide the core of the + functionality for the whole system. They are, in essence, a set of blocks + which can be combined in myriad ways, like Lego (tm). The packages in the + previous level are 'just' pre-fabricated combinations to cover the most + important use cases. + + The list of packages belonging to this layer can be found in section [Core + Packages](#subsection2) + + 1. Last, but not least is the layer containing support packages providing + generic functionality which not necessarily belong into the module. + + The list of packages belonging to this layer can be found in section + [Support Packages](#subsection3) + +## User Packages + + - __[pt::pgen](pt_pgen.md)__ + +## Core Packages + +This layer is further split into six sections handling the storage, import, +export, transformation, and execution of grammars, plus grammar specific support +packages. + + - Storage + + * __[pt::peg::container](pt_peg_container.md)__ + + - Export + + * __[pt::peg::export](pt_peg_export.md)__ + + * __[pt::peg::export::container](pt_peg_export_container.md)__ + + * __[pt::peg::export::json](pt_peg_export_json.md)__ + + * __[pt::peg::export::peg](pt_peg_export_peg.md)__ + + * __[pt::peg::to::container](pt_peg_to_container.md)__ + + * __[pt::peg::to::json](pt_peg_to_json.md)__ + + * __[pt::peg::to::peg](pt_peg_to_peg.md)__ + + * __[pt::peg::to::param](pt_peg_to_param.md)__ + + * __[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ + + * __[pt::peg::to::cparam](pt_peg_to_cparam.md)__ + + - Import + + * __[pt::peg::import](pt_peg_import.md)__ + + * __[pt::peg::import::container](pt_peg_import_container.md)__ + + * __[pt::peg::import::json](pt_peg_import_json.md)__ + + * __[pt::peg::import::peg](pt_peg_import_peg.md)__ + + * __[pt::peg::from::container](pt_peg_from_container.md)__ + + * __[pt::peg::from::json](pt_peg_from_json.md)__ + + * __[pt::peg::from::peg](pt_peg_from_peg.md)__ + + - Transformation + + - Execution + + * __[pt::peg::interp](pt_peg_interp.md)__ + + * __[pt::rde](pt_rdengine.md)__ + + - Support + + * __[pt::tclparam::configuration::snit](pt_tclparam_config_snit.md)__ + + * __[pt::tclparam::configuration::tcloo](pt_tclparam_config_tcloo.md)__ + + * __[pt::cparam::configuration::critcl](pt_cparam_config_critcl.md)__ + + * __[pt::ast](pt_astree.md)__ + + * __[pt::pe](pt_pexpression.md)__ + + * __[pt::peg](pt_pegrammar.md)__ + +## Support Packages + + - __[pt::peg::container::peg](pt_peg_container_peg.md)__ + + - __text::write__ + + - __configuration__ + + - __paths__ + + - __char__ + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_json_language.md Index: embedded/md/tcllib/files/modules/pt/pt_json_language.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_json_language.md @@ -0,0 +1,487 @@ + +[//000000001]: # (pt::json_language - Parser Tools) +[//000000002]: # (Generated from file 'pt_json_language.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::json_language(n) 1 tcllib "Parser Tools") + +# NAME + +pt::json_language - The JSON Grammar Exchange Format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Example](#subsection1) + + - [PEG serialization format](#section2) + + - [Example](#subsection2) + + - [PE serialization format](#section3) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +The __json__ format for parsing expression grammars was written as a data +exchange format not bound to Tcl. It was defined to allow the exchange of +grammars with PackRat/PEG based parser generators for other languages. + +It is formally specified by the rules below: + + 1. The JSON of any PEG is a JSON object. + + 1. This object holds a single key, __pt::grammar::peg__, and its value. This + value holds the contents of the grammar. + + 1. The contents of the grammar are a JSON object holding the set of + nonterminal symbols and the starting expression. The relevant keys and + their values are + + - __rules__ + + The value is a JSON object whose keys are the names of the nonterminal + symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a JSON object itself. The relevant keys + and their values in this dictionary are + + * __is__ + + The value is a JSON string holding the Tcl serialization of + the parsing expression describing the symbols sentennial + structure, as specified in the section [PE serialization + format](#section3). + + * __mode__ + + The value is a JSON holding holding one of three values + specifying how a parser should handle the semantic value + produced by the symbol. + + + __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node for + the nonterminal itself, which has the ASTs of the symbol's + right hand side as its children. + + + __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node for + the nonterminal, without any children. Any ASTs generated + by the symbol's right hand side are discarded. + + + __void__ + + The nonterminal has no semantic value. Any ASTs generated + by the symbol's right hand side are discarded (as well). + + - __start__ + + The value is a JSON string holding the Tcl serialization of the start + parsing expression of the grammar, as specified in the section [PE + serialization format](#section3). + + 1. The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + +As an aside to the advanced reader, this is pretty much the same as the Tcl +serialization of PE grammars, as specified in section [PEG serialization +format](#section2), except that the Tcl dictionaries and lists of that format +are mapped to JSON objects and arrays. Only the parsing expressions themselves +are not translated further, but kept as JSON strings containing a nested Tcl +list, and there is no concept of canonicity for the JSON either. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +a JSON serialization for it is + + { + "pt::grammar::peg" : { + "rules" : { + "AddOp" : { + "is" : "\/ {t -} {t +}", + "mode" : "value" + }, + "Digit" : { + "is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}", + "mode" : "value" + }, + "Expression" : { + "is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}", + "mode" : "value" + }, + "Factor" : { + "is" : "x {n Term} {* {x {n AddOp} {n Term}}}", + "mode" : "value" + }, + "MulOp" : { + "is" : "\/ {t *} {t \/}", + "mode" : "value" + }, + "Number" : { + "is" : "x {? {n Sign}} {+ {n Digit}}", + "mode" : "value" + }, + "Sign" : { + "is" : "\/ {t -} {t +}", + "mode" : "value" + }, + "Term" : { + "is" : "n Number", + "mode" : "value" + } + }, + "start" : "n Expression" + } + } + +and a Tcl serialization of the same is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +The similarity of the latter to the JSON should be quite obvious. + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section3). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section3). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_param.md Index: embedded/md/tcllib/files/modules/pt/pt_param.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_param.md @@ -0,0 +1,628 @@ + +[//000000001]: # (pt::param - Parser Tools) +[//000000002]: # (Generated from file 'pt_param.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::param(n) 1 tcllib "Parser Tools") + +# NAME + +pt::param - PackRat Machine Specification + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Architectural State](#section2) + + - [Instruction Set](#section3) + + - [Input Handling](#subsection1) + + - [Character Processing](#subsection2) + + - [Error Handling](#subsection3) + + - [Status Control](#subsection4) + + - [Location Handling](#subsection5) + + - [Nonterminal Execution](#subsection6) + + - [Value Construction](#subsection7) + + - [AST Construction](#subsection8) + + - [Control Flow](#subsection9) + + - [Interaction of the Instructions with the Architectural State](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +Welcome to the PackRat Machine (short: *[PARAM](../../../../index.md#param)*), a +virtual machine geared towards the support of recursive descent parsers, +especially packrat parsers. Towards this end it has features like the caching +and reuse of partial results, the caching of the encountered input, and the +ability to backtrack in both input and AST creation. + +This document specifies the machine in terms of its architectural state and +instruction set. + +# Architectural State + +Any PARAM implementation has to manage at least the following state: + + - *Input* (IN) + + This is the channel the characters to process are read from. + + This part of the machine's state is used and modified by the instructions + defined in the section [Input Handling](#subsection1). + + - *Current Character* (CC) + + The character from the *input* currently tested against its possible + alternatives. + + This part of the machine's state is used and modified by the instructions + defined in the section [Character Processing](#subsection2). + + - *Current Location* (CL) + + The location of the *current character* in the *input*, as offset relative + to the beginning of the input. Character offsets are counted from __0__. + + This part of the machine's state is used and modified by the instructions + defined in the sections [Character Processing](#subsection2), [Location + Handling](#subsection5), and [Nonterminal Execution](#subsection6). + + - *Location Stack* (LS) + + A stack of locations in the *input*, saved for possible backtracking. + + This part of the machine's state is used and modified by the instructions + defined in the sections [Character Processing](#subsection2), [Location + Handling](#subsection5), and [Nonterminal Execution](#subsection6). + + - *Status* (ST) + + The status of the last attempt of testing the *input*, indicating either + success or failure. + + This part of the machine's state is used and modified by the instructions + defined in the sections [Status Control](#subsection4), [Character + Processing](#subsection2), and [Nonterminal Execution](#subsection6). + + - *Semantic Value* (SV) + + The current semantic value, either empty, or a node for AST constructed from + the input. + + This part of the machine's state is used and modified by the instructions + defined in the sections [Value Construction](#subsection7), and [AST + Construction](#subsection8). + + - *AST Reduction Stack* (ARS) + + The stack of partial ASTs constructed during the processing of nonterminal + symbols. + + This part of the machine's state is used and modified by the instructions + defined in the sections [Value Construction](#subsection7), and [AST + Construction](#subsection8). + + - *AST Stack* (AS) + + The stack of reduction stacks, saved for possible backtracking. + + This part of the machine's state is used and modified by the instructions + defined in the sections [Value Construction](#subsection7), and [AST + Construction](#subsection8). + + - *Error Status* (ER) + + The machine's current knowledge of errors. This is either empty, or set to a + pair of location in the input and the set of messages for that location. + + *Note* that this part of the machine's state can be set even if the last + test of the *current character* was successful. For example, the *-operator + (matching a sub-expression zero or more times) in a PEG is always + successful, even if it encounters a problem further in the input and has to + backtrack. Such problems must not be forgotten when continuing the parsing. + + This part of the machine's state is used and modified by the instructions + defined in the sections [Error Handling](#subsection3), [Character + Processing](#subsection2), and [Nonterminal Execution](#subsection6). + + - *Error Stack* (ES) + + The stack of error stati, saved for backtracking. This enables the machine + to merge current and older error stati when performing backtracking in + choices after an failed match. + + This part of the machine's state is used and modified by the instructions + defined in the sections [Error Handling](#subsection3), [Character + Processing](#subsection2), and [Nonterminal Execution](#subsection6). + + - *Nonterminal Cache* (NC) + + A cache of machine states keyed by pairs name of nonterminal symbol and + location in the input. Each pair (N, L) is associated with a 4-tuple holding + the values to use for CL, ST, SV, and ER after the nonterminal N was parsed + starting from the location L. It is a performance aid for backtracking + parsers, allowing them to avoid an expensive reparsing of complex + nonterminal symbols if they have been encountered before at a given + location. + + The key location is where machine started the attempt to match the named + nonterminal symbol, and the location in the saved 4-tuple is where machine + ended up after the attempt completed, independent of the success of the + attempt. + + This part of the machine's state is used and modified by the instructions + defined in the section [Nonterminal Execution](#subsection6). + + - *Terminal Cache* (TC) + + A cache of characters read from IN, with their location in IN as pair of + line and column, keyed by the location in IN, this time as character offset + from the beginning of IN. It is a performance aid for backtracking parsers, + allowing them to avoid a possibly expensive rereading of characters from IN, + or even enabling backtracking at, i.e. in the case of IN not randomly + seekable. + + This part of the machine's state is used and modified by the instructions + defined in the section [Input Handling](#subsection1). + +# Instruction Set + +With the machine's architectural state specified it is now possible to specify +the instruction set operating on that state and to be implemented by any +realization of the PARAM. The 37 instructions are grouped roughly by the state +they influence and/or query during their execution. + +## Input Handling + +The instructions in this section mainly access IN, pulling the characters to +process into the machine. + + - __input_next__ *msg* + + This method reads the next character, i.e. the character after CL, from IN. + If successful this character becomes CC, CL is advanced by one, ES is + cleared, and the operation is recorded as a success in ST. + + The operation may read the character from IN if the next character is not + yet known to TC. If successful the new character is stored in TC, with its + location (line, column), and the operation otherwise behaves as specified + above. Future reads from the same location, possible due to backtracking, + will then be satisfied from TC instead of IN. + + If, on the other hand, the end of IN was reached, the operation is recorded + as failed in ST, CL is left unchanged, and the pair of CL and *msg* becomes + the new ES. + +## Character Processing + +The instructions in this section mainly access CC, testing it against character +classes, ranges, and individual characters. + + - __test_alnum__ + + This instruction implements the special PE operator "alnum", which checks if + CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_alpha__ + + This instruction implements the special PE operator "alpha", which checks if + CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_ascii__ + + This instruction implements the special PE operator "ascii", which checks if + CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_char__ *char* + + This instruction implements the character matching operator, i.e. it checks + if CC is *char*. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_ddigit__ + + This instruction implements the special PE operator "ddigit", which checks + if CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_digit__ + + This instruction implements the special PE operator "digit", which checks if + CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_graph__ + + This instruction implements the special PE operator "graph", which checks if + CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_lower__ + + This instruction implements the special PE operator "lower", which checks if + CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_print__ + + This instruction implements the special PE operator "print", which checks if + CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_punct__ + + This instruction implements the special PE operator "punct", which checks if + CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_range__ *chars* *chare* + + This instruction implements the range matching operator, i.e. it checks if + CC falls into the interval of characters spanned up by the two characters + from *chars* to *chare*, both inclusive. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_space__ + + This instruction implements the special PE operator "space", which checks if + CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_upper__ + + This instruction implements the special PE operator "upper", which checks if + CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_wordchar__ + + This instruction implements the special PE operator "wordchar", which checks + if CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + + - __test_xdigit__ + + This instruction implements the special PE operator "xdigit", which checks + if CC falls into the character class of the same name, or not. + + Success and failure of the test are both recorded directly in ST. Success + further clears ES, wheras failure sets the pair of CL and expected input + (encoded as a leaf parsing expression) as the new ES and then rewinds CL by + one character, preparing the machine for another parse attempt by a possible + alternative. + +## Error Handling + +The instructions in this section mainly access ER and ES. + + - __error_clear__ + + This instruction clears ER. + + - __error_push__ + + This instruction makes a copy of ER and pushes it on ES. + + - __error_pop_merge__ + + This instruction takes the topmost entry of ES and merges the error status + it contains with ES, making the result the new ES. + + The merge is governed by four rules, with the merge result + + Empty if both states are empty. + + The non-empty state if only one of the two states is non-empty. + + The state with the larger location, if the two states specify different + locations. + + The pair of the location shared by the two states, and the set-union of + their messages for states at the same location. + + - __error_nonterminal__ *symbol* + + This is a guarded instruction. It does nothing if either ES is empty, or if + the location in ES is not just past the last location saved in LS. Otherwise + it sets the pair of that location and the nonterminal *symbol* as the new + ES. + + *Note*: In the above "just past" means "that location plus one", or also + "the location of the next character after that location". + +## Status Control + +The instructions in this section directly manipulate ST. + + - __status_ok__ + + This instruction sets ST to __true__, recording a success. + + - __status_fail__ + + This instruction sets ST to __false__, recording a failure. + + - __status_negate__ + + This instruction negates ST, turning a failure into a success and vice + versa. + +## Location Handling + +The instructions in this section access CL and LS. + + - __loc_push__ + + This instruction makes a copy of CL and pushes it on LS. + + - __loc_pop_discard__ + + This instructions pops the last saved location from LS. + + - __loc_pop_rewind__ + + This instruction pops the last saved location from LS and restores it as CL. + +## Nonterminal Execution + +The instructions in this section access and manipulate NC. + + - __symbol_restore__ *symbol* + + This instruction checks if NC contains data for the nonterminal *symbol* at + CL, or not. The result of the instruction is a boolean flag, with __True__ + indicating that data was found in the cache. In that case the instruction + has further updated the architectural state of the machine with the cached + information, namely CL, ST, ER, and SV. + + The method with which the instruction's result is transformed into control + flow is left undefined and the responsibility of the implementation. + + - __symbol_save__ *symbol* + + This instructions saves the current settings of CL, ST, ER, and SV in NC, + using the pair of nonterminal *symbol* and the last location saved in LS as + key. + +## Value Construction + +The instructions in this section manipulate SV. + + - __value_clear__ + + This instruction clears SV. + + - __value_leaf__ *symbol* + + This instruction constructs an AST node for *symbol* covering the range of + IN from one character after the last location saved on LS to CL and stores + it in SV. ... + + - __value_reduce__ *symbol* + + This instruction generally behaves like __value_nonterminal_leaf__, except + that it takes all AST nodes on ARS, if any, and makes them the children of + the new node, with the last node saved on ARS becoming the right-most / last + child. Note that ARS is not modfied by this operation. + +## AST Construction + +The instructions in this section manipulate ARS and AS. + + - __ast_value_push__ + + This instruction makes a copy of SV and pushes it on ARS. + + - __ast_push__ + + This instruction pushes the current state of ARS on AS and then clears ARS. + + - __ast_pop_rewind__ + + This instruction pops the last entry saved on AS and restores it as the new + state of ARS. + + - __ast_pop_discard__ + + This instruction pops the last entry saved on AS. + +## Control Flow + +Normally this section would contain the specifications of the control flow +instructions of the PARAM, i.e. (un)conditional jumps and the like. However, +this part of the PARAM is intentionally left unspecified. This allows the +implementations to freely choose how to implement control flow. + +The implementation of this machine in Parser Tools, i.e the package +__[pt::rde](pt_rdengine.md)__, is not only coded in Tcl, but also relies on Tcl +commands to provide it with control flow (instructions). + +# Interaction of the Instructions with the Architectural State + + Instruction Inputs Outputs + ======================= ======================= ==================== + ast_pop_discard AS -> AS + ast_pop_rewind AS -> AS, ARS + ast_push ARS, AS -> AS + ast_value_push SV, ARS -> ARS + ======================= ======================= ==================== + error_clear - -> ER + error_nonterminal sym ER, LS -> ER + error_pop_merge ES, ER -> ER + error_push ES, ER -> ES + ======================= ======================= ==================== + input_next msg IN -> TC, CL, CC, ST, ER + ======================= ======================= ==================== + loc_pop_discard LS -> LS + loc_pop_rewind LS -> LS, CL + loc_push CL, LS -> LS + ======================= ======================= ==================== + status_fail - -> ST + status_negate ST -> ST + status_ok - -> ST + ======================= ======================= ==================== + symbol_restore sym NC -> CL, ST, ER, SV + symbol_save sym CL, ST, ER, SV LS -> NC + ======================= ======================= ==================== + test_alnum CC -> ST, ER + test_alpha CC -> ST, ER + test_ascii CC -> ST, ER + test_char char CC -> ST, ER + test_ddigit CC -> ST, ER + test_digit CC -> ST, ER + test_graph CC -> ST, ER + test_lower CC -> ST, ER + test_print CC -> ST, ER + test_punct CC -> ST, ER + test_range chars chare CC -> ST, ER + test_space CC -> ST, ER + test_upper CC -> ST, ER + test_wordchar CC -> ST, ER + test_xdigit CC -> ST, ER + ======================= ======================= ==================== + value_clear - -> SV + value_leaf symbol LS, CL -> SV + value_reduce symbol ARS, LS, CL -> SV + ======================= ======================= ==================== + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer), [virtual +machine](../../../../index.md#virtual_machine) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_parse_peg.md Index: embedded/md/tcllib/files/modules/pt/pt_parse_peg.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_parse_peg.md @@ -0,0 +1,157 @@ + +[//000000001]: # (pt_parse_peg - Parser Tools) +[//000000002]: # (Generated from file 'pt_parse_peg.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt_parse_peg(i) 1 tcllib "Parser Tools") + +# NAME + +pt_parse_peg - Parser Tools PEG Parser + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Class API](#section2) + + - [Instances API](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::parse::peg 1 + +[__pt::parse::peg__ ?*objectName*?](#1) +[*objectName* __destroy__](#2) +[*objectName* __parse__ *chan*](#3) +[*objectName* __parset__ *text*](#4) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides a class whose instances are parsers for parsing expression +grammars in textual form. + +# Class API + + - __pt::parse::peg__ ?*objectName*? + + The class command constructs parser instances, i.e. objects. The result of + the command is the fully-qualified name of the instance command. + + If no *objectName* is specified the class will generate and use an automatic + name. If the *objectName* was specified, but is not fully qualified the + command will be created in the current namespace. + +# Instances API + +All parser instances provide at least the methods shown below: + + - *objectName* __destroy__ + + This method destroys the parser instance, releasing all claimed memory and + other resources, and deleting the instance command. + + The result of the command is the empty string. + + - *objectName* __parse__ *chan* + + This method runs the parser using the contents of *chan* as input (starting + at the current location in the channel), until parsing is not possible + anymore, either because parsing has completed, or run into a syntax error. + + Note here that the Parser Tools are based on Tcl 8.5+. In other words, the + channel argument is not restricted to files, sockets, etc. We have the full + power of *reflected channels* available. + + It should also be noted that the parser pulls the characters from the input + stream as it needs them. If a parser created by this package has to be + operated in a push aka event-driven manner it will be necessary to go to Tcl + 8.6+ and use the __[coroutine::auto](../coroutine/coro_auto.md)__ to wrap it + into a coroutine where __[read](../../../../index.md#read)__ is properly + changed for push-operation. + + Upon successful completion the command returns an abstract syntax tree as + its result. This AST is in the form specified in section __AST serialization + format__. As a plain nested Tcl-list it can then be processed with any Tcl + commands the user likes, doing transformations, semantic checks, etc. To + help in this the package __[pt::ast](pt_astree.md)__ provides a set of + convenience commands for validation of the tree's basic structure, printing + it for debugging, and walking it either from the bottom up, or top down. + + When encountering a syntax error the command will throw an error instead. + This error will be a 4-element Tcl-list, containing, in the order listed + below: + + The string __pt::rde__ identifying it as parser runtime error. + + The location of the parse error, as character offset from the beginning of + the parsed input. + + The location of parse error, now as a 2-element list containing line-number + and column in the line. + + A set of atomic parsing expressions indicating encoding the characters + and/or nonterminal symbols the parser expected to see at the location of the + parse error, but did not get. For the specification of atomic parsing + expressions please see the section __PE serialization format__. + + - *objectName* __parset__ *text* + + This method runs the parser using the string in *text* as input. In all + other ways it behaves like the method __parse__, shown above. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_parser_api.md Index: embedded/md/tcllib/files/modules/pt/pt_parser_api.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_parser_api.md @@ -0,0 +1,425 @@ + +[//000000001]: # (pt_parser_api - Parser Tools) +[//000000002]: # (Generated from file 'pt_parser_api.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt_parser_api(i) 1 tcllib "Parser Tools") + +# NAME + +pt_parser_api - Parser API + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Class API](#section2) + + - [Instance API](#section3) + + - [Usage](#section4) + + - [AST serialization format](#section5) + + - [Example](#subsection1) + + - [PE serialization format](#section6) + + - [Example](#subsection2) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 + +[__className__ ?*objectName*?](#1) +[*objectName* __destroy__](#2) +[*objectName* __parse__ *chan*](#3) +[*objectName* __parset__ *text*](#4) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This document describes the API shared by the grammar interpreter provided by +the package __[pt::peg::interp](pt_peg_interp.md)__ and the parsers generated by +the __[pt](../../apps/pt.md)__ application for the result formats __critcl__, +__snit__, and __oo__ regarding access to the actual parsing functionality. + +Its intended audience are people who wish to create a parser for some language +of theirs and then use that parser within a Tcl-based package or application. + +It resides in the User Layer of Parser Tools. + +![](../../../../image/arch_user_pkg.png) + +# Class API + + - __className__ ?*objectName*? + + The class command constructs parser instances, i.e. objects. The result of + the command is the fully-qualified name of the instance command. + + If no *objectName* is specified the class will generate and use an automatic + name. If the *objectName* was specified, but is not fully qualified the + command will be created in the current namespace. + +# Instance API + +All parser instances provide at least the methods shown below: + + - *objectName* __destroy__ + + This method destroys the parser instance, releasing all claimed memory and + other resources, and deleting the instance command. + + The result of the command is the empty string. + + - *objectName* __parse__ *chan* + + This method runs the parser using the contents of *chan* as input (starting + at the current location in the channel), until parsing is not possible + anymore, either because parsing has completed, or run into a syntax error. + + Note here that the Parser Tools are based on Tcl 8.5+. In other words, the + channel argument is not restricted to files, sockets, etc. We have the full + power of *reflected channels* available. + + It should also be noted that the parser pulls the characters from the input + stream as it needs them. If a parser created by this package has to be + operated in a push aka event-driven manner it will be necessary to go to Tcl + 8.6+ and use the __[coroutine::auto](../coroutine/coro_auto.md)__ to wrap it + into a coroutine where __[read](../../../../index.md#read)__ is properly + changed for push-operation. + + Upon successful completion the command returns an abstract syntax tree as + its result. This AST is in the form specified in section [AST serialization + format](#section5). As a plain nested Tcl-list it can then be processed with + any Tcl commands the user likes, doing transformations, semantic checks, + etc. To help in this the package __[pt::ast](pt_astree.md)__ provides a set + of convenience commands for validation of the tree's basic structure, + printing it for debugging, and walking it either from the bottom up, or top + down. + + When encountering a syntax error the command will throw an error instead. + This error will be a 4-element Tcl-list, containing, in the order listed + below: + + The string __pt::rde__ identifying it as parser runtime error. + + The location of the parse error, as character offset from the beginning of + the parsed input. + + The location of parse error, now as a 2-element list containing line-number + and column in the line. + + A set of atomic parsing expressions indicating encoding the characters + and/or nonterminal symbols the parser expected to see at the location of the + parse error, but did not get. For the specification of atomic parsing + expressions please see the section [PE serialization format](#section6). + + - *objectName* __parset__ *text* + + This method runs the parser using the string in *text* as input. In all + other ways it behaves like the method __parse__, shown above. + +# Usage + +A generated parser is used like this + + package require the-parser-package ;# Generated by result-formats 'critcl', 'snit' or 'oo' of 'pt'. + set parser [the-parser-class] + + set ast [$parser parse $channel] + ... process the abstract syntax tree ... + +When using a grammar interpreter for parsing some differences creep in + + package require the-grammar-package ;# Generated by result-format 'container' of 'pt'. + set grammar [the-grammar-class] + + package require pt::peg::interp + set parser [pt::peg::interp] + + $parser use $grammar + + set ast [$parser parse $channel] + $parser destroy + + ... process the abstract syntax tree ... + +# AST serialization format + +Here we specify the format used by the Parser Tools to serialize Abstract Syntax +Trees (ASTs) as immutable values for transport, comparison, etc. + +Each node in an AST represents a nonterminal symbol of a grammar, and the range +of tokens/characters in the input covered by it. ASTs do not contain terminal +symbols, i.e. tokens/characters. These can be recovered from the input given a +symbol's location. + +We distinguish between *regular* and *canonical* serializations. While a tree +may have more than one regular serialization only exactly one of them will be +*canonical*. + + - Regular serialization + + The serialization of any AST is the serialization of its root node. + + The serialization of any node is a Tcl list containing at least three + elements. + + The first element is the name of the nonterminal symbol stored in the node. + + The second and third element are the locations of the first and last token + in the token stream the node represents (covers). + + Locations are provided as non-negative integer offsets from the beginning of + the token stream, with the first token found in the stream located at offset + 0 (zero). + + The end location has to be equal to or larger than the start location. + + All elements after the first three represent the children of the node, which + are themselves nodes. This means that the serializations of nodes without + children, i.e. leaf nodes, have exactly three elements. The children are + stored in the list with the leftmost child first, and the rightmost child + last. + + - Canonical serialization + + The canonical serialization of an abstract syntax tree has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this tree. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the parsing expression grammar below + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +and the input string + + 120+5 + +then a parser should deliver the abstract syntax tree below (except for +whitespace) + + set ast {Expression 0 4 + {Factor 0 4 + {Term 0 2 + {Number 0 2 + {Digit 0 0} + {Digit 1 1} + {Digit 2 2} + } + } + {AddOp 3 3} + {Term 4 4 + {Number 4 4 + {Digit 4 4} + } + } + } + } + +Or, more graphical + +![](../../../../image/expr_ast.png) + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_container.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_container.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_container.md @@ -0,0 +1,665 @@ + +[//000000001]: # (pt::peg::container - Parser Tools) +[//000000002]: # (Generated from file 'pt_peg_container.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::container(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::container - PEG Storage + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Class API](#subsection1) + + - [Object API](#subsection2) + + - [PEG serialization format](#section2) + + - [Example](#subsection3) + + - [PE serialization format](#section3) + + - [Example](#subsection4) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit +package require pt::peg::container ?1? + +[__::pt::peg__ *objectName* ?__=__|__:=__|__<--__|__as__|__deserialize__ *src*?](#1) +[*objectName* __destroy__](#2) +[*objectName* __clear__](#3) +[*objectName* __importer__](#4) +[*objectName* __importer__ *object*](#5) +[*objectName* __exporter__](#6) +[*objectName* __exporter__ *object*](#7) +[*objectName* __=__ *source*](#8) +[*objectName* __-->__ *destination*](#9) +[*objectName* __serialize__ ?*format*?](#10) +[*objectName* __deserialize =__ *data* ?*format*?](#11) +[*objectName* __deserialize +=__ *data* ?*format*?](#12) +[*objectName* __start__](#13) +[*objectName* __start__ *pe*](#14) +[*objectName* __nonterminals__](#15) +[*objectName* __modes__](#16) +[*objectName* __modes__ *dict*](#17) +[*objectName* __rules__](#18) +[*objectName* __rules__ *dict*](#19) +[*objectName* __add__ ?*nt*...?](#20) +[*objectName* __remove__ ?*nt*...?](#21) +[*objectName* __exists__ *nt*](#22) +[*objectName* __rename__ *ntold* *ntnew*](#23) +[*objectName* __mode__ *nt*](#24) +[*objectName* __mode__ *nt* *mode*](#25) +[*objectName* __rule__ *nt*](#26) +[*objectName* __rule__ *nt* *pe*](#27) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides a container class for parsing expression grammars, with +each instance storing a single grammar and allowing the user to manipulate and +query its definition. + +It resides in the Storage section of the Core Layer of Parser Tools, and is one +of the three pillars the management of parsing expression grammars resides on. + +![](../../../../image/arch_core_container.png) The other two pillars are, as +shown above + + 1. *[PEG Import](pt_peg_import.md)*, and + + 1. *[PEG Export](pt_peg_export.md)* + +Packages related to this are: + + - __[pt::rde](pt_rdengine.md)__ + + This package provides an implementation of PARAM, a virtual machine for the + parsing of a channel, geared towards the needs of handling PEGs. + + - __[pt::peg::interp](pt_peg_interp.md)__ + + This package implements an interpreter for PEGs on top of the virtual + machine provided by __pt::peg::rde__ + +## Class API + +The package exports the API described here. + + - __::pt::peg__ *objectName* ?__=__|__:=__|__<--__|__as__|__deserialize__ *src*? + + The command creates a new container object for a parsing expression grammar + and returns the fully qualified name of the object command as its result. + The API of this object command is described in the section [Object + API](#subsection2). It may be used to invoke various operations on the + object. + + The new container will be empty if no *src* is specified. Otherwise it will + contain a copy of the grammar contained in the *src*. All operators except + __deserialize__ interpret *src* as a container object command. The + __deserialize__ operator interprets *src* as the serialization of a parsing + expression grammar instead, as specified in section [PEG serialization + format](#section2). + + An empty grammar has no nonterminal symbols, and the start expression is the + empty expression, i.e. epsilon. It is *valid*, but not *useful*. + +## Object API + +All objects created by this package provide the following methods for the +manipulation and querying of their contents: + + - *objectName* __destroy__ + + This method destroys the object, releasing all claimed memory, and deleting + the associated object command. + + - *objectName* __clear__ + + This method resets the object to contain the empty grammar. It does *not* + destroy the object itself. + + - *objectName* __importer__ + + This method returns the import manager object currently attached to the + container, if any. + + - *objectName* __importer__ *object* + + This method attaches the *object* as import manager to the container, and + returns it as the result of the command. Note that the *object* is *not* put + into ownership of the container. I.e., destruction of the container will + *not* destroy the *object*. + + It is expected that *object* provides a method named __import text__ which + takes a text and a format name, and returns the canonical serialization of + the table of contents contained in the text, assuming the given format. + + - *objectName* __exporter__ + + This method returns the export manager object currently attached to the + container, if any. + + - *objectName* __exporter__ *object* + + This method attaches the *object* as export manager to the container, and + returns it as the result of the command. Note that the *object* is *not* put + into ownership of the container. I.e., destruction of the container will + *not* destroy the *object*. + + It is expected that *object* provides a method named __export object__ which + takes the container and a format name, and returns a text encoding table of + contents stored in the container, in the given format. It is further + expected that the *object* will use the container's method __serialize__ to + obtain the serialization of the table of contents from which to generate the + text. + + - *objectName* __=__ *source* + + This method assigns the contents of the PEG object *source* to ourselves, + overwriting the existing definition. This is the assignment operator for + grammars. + + This operation is in effect equivalent to + + *objectName* __deserialize =__ [*source* __serialize__] + + - *objectName* __-->__ *destination* + + This method assigns our contents to the PEG object *destination*, + overwriting the existing definition. This is the reverse assignment operator + for grammars. + + This operation is in effect equivalent to + + *destination* __deserialize =__ [*objectName* __serialize__] + + - *objectName* __serialize__ ?*format*? + + This method returns our grammar in some textual form usable for transfer, + persistent storage, etc. If no *format* is not specified the returned result + is the canonical serialization of the grammar, as specified in the section + [PEG serialization format](#section2). + + Otherwise the object will use the attached export manager to convert the + data to the specified format. In that case the method will fail with an + error if the container has no export manager attached to it. + + - *objectName* __deserialize =__ *data* ?*format*? + + This is the complementary method to __serialize__. It replaces the current + definition with the grammar contained in the *data*. If no *format* was + specified it is assumed to be the regular serialization of a grammar, as + specified in the section [PEG serialization format](#section2) + + Otherwise the object will use the attached import manager to convert the + data from the specified format to a serialization it can handle. In that + case the method will fail with an error if the container has no import + manager attached to it. + + The result of the method is the empty string. + + - *objectName* __deserialize +=__ *data* ?*format*? + + This method behaves like __deserialize =__ in its essentials, except that it + merges the grammar in the *data* to its contents instead of replacing it. + The method will fail with an error and leave the grammar unchanged if + merging is not possible, i.e. would produce an invalid grammar. + + The result of the method is the empty string. + + - *objectName* __start__ + + This method returns the current start expression of the grammar. + + - *objectName* __start__ *pe* + + This method defines the *start expression* of the grammar. It replaces the + current start expression with the parsing expression *pe*, and returns the + new start expression. + + The method will fail with an error and leave the grammar unchanged if *pe* + does not contain a valid parsing expression as specified in the section [PE + serialization format](#section3). + + - *objectName* __nonterminals__ + + This method returns the set of all nonterminal symbols known to the grammar. + + - *objectName* __modes__ + + This method returns a dictionary mapping the set of all nonterminal symbols + known to the grammar to their semantic modes. + + - *objectName* __modes__ *dict* + + This method takes a dictionary mapping a set of nonterminal symbols known to + the grammar to their semantic modes, and returns the new full mapping of + nonterminal symbols to semantic modes. + + The method will fail with an error if any of the nonterminal symbols in the + dictionary is not known to the grammar, or the empty string, i.e. an invalid + nonterminal symbol, or if any the chosen *mode*s is not one of the legal + values. + + - *objectName* __rules__ + + This method returns a dictionary mapping the set of all nonterminal symbols + known to the grammar to their parsing expressions (right-hand sides). + + - *objectName* __rules__ *dict* + + This method takes a dictionary mapping a set of nonterminal symbols known to + the grammar to their parsing expressions (right-hand sides), and returns the + new full mapping of nonterminal symbols to parsing expressions. + + The method will fail with an error any of the nonterminal symbols in the + dictionary is not known to the grammar, or the empty string, i.e. an invalid + nonterminal symbol, or any of the chosen parsing expressions is not a valid + parsing expression as specified in the section [PE serialization + format](#section3). + + - *objectName* __add__ ?*nt*...? + + This method adds the nonterminal symbols *nt*, etc. to the grammar, and + defines default semantic mode and expression for it (__value__ and + __epsilon__ respectively). The method returns the empty string as its + result. + + The method will fail with an error and leaves the grammar unchanged if any + of the nonterminal symbols are either already defined in our grammar, or are + the empty string (an invalid nonterminal symbol). + + The method does nothing if no symbol was specified as argument. + + - *objectName* __remove__ ?*nt*...? + + This method removes the named nonterminal symbols *nt*, etc. from the set of + nonterminal symbols known to our grammar. The method returns the empty + string as its result. + + The method will fail with an error and leave the grammar unchanged if any of + the nonterminal symbols is not known to the grammar, or is the empty string, + i.e. an invalid nonterminal symbol. + + - *objectName* __exists__ *nt* + + This method tests whether the nonterminal symbol *nt* is known to our + grammar or not. The result is a boolean value. It will be set to __true__ if + *nt* is known, and __false__ otherwise. + + The method will fail with an error if *nt* is the empty string, i.e. an + invalid nonterminal symbol. + + - *objectName* __rename__ *ntold* *ntnew* + + This method renames the nonterminal symbol *ntold* to *ntnew*. The method + returns the empty string as its result. + + The method will fail with an error and leave the grammar unchanged if either + *ntold* is not known to the grammar, or *ntnew* is already known, or any of + them is the empty string, i.e. an invalid nonterminal symbol. + + - *objectName* __mode__ *nt* + + This method returns the current semantic mode for the nonterminal symbol + *nt*. + + The method will fail with an error if *nt* is not known to the grammar, or + the empty string, i.e. an invalid nonterminal symbol. + + - *objectName* __mode__ *nt* *mode* + + This mode sets the semantic mode for the nonterminal symbol *nt*, and + returns the new mode. The method will fail with an error if *nt* is not + known to the grammar, or the empty string, i.e. an invalid nonterminal + symbol, or the chosen *mode* is not one of the legal values. + + The following modes are legal: + + * __value__ + + The semantic value of the nonterminal symbol is an abstract syntax tree + consisting of a single node node for the nonterminal itself, which has + the ASTs of the symbol's right hand side as its children. + + * __leaf__ + + The semantic value of the nonterminal symbol is an abstract syntax tree + consisting of a single node node for the nonterminal, without any + children. Any ASTs generated by the symbol's right hand side are + discarded. + + * __void__ + + The nonterminal has no semantic value. Any ASTs generated by the + symbol's right hand side are discarded (as well). + + - *objectName* __rule__ *nt* + + This method returns the current parsing expression (right-hand side) for the + nonterminal symbol *nt*. + + The method will fail with an error if *nt* is not known to the grammar, or + the empty string, i.e. an invalid nonterminal symbol. + + - *objectName* __rule__ *nt* *pe* + + This method set the parsing expression (right-hand side) of the nonterminal + *nt* to *pe*, and returns the new parsing expression. + + The method will fail with an error if *nt* is not known to the grammar, or + the empty string, i.e. an invalid nonterminal symbol, or *pe* does not + contain a valid parsing expression as specified in the section [PE + serialization format](#section3). + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section3). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section3). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_container_peg.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_container_peg.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_container_peg.md @@ -0,0 +1,86 @@ + +[//000000001]: # (pt::peg::container::peg - Parser Tools) +[//000000002]: # (Generated from file 'pt_peg_container_peg.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::container::peg(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::container::peg - PEG Storage. Canned PEG grammar specification + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit +package require pt::peg::container::peg ?1? +package require pt::peg::container + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides a sub-type of +__[pt::peg::container](pt_peg_container.md)__ which is preloaded with a parsing +expression grammar describing a textual format for parsing expression grammars. + +The sub-type provides the exact same API as +__[pt::peg::container](pt_peg_container.md)__. Instead of duplicating its +contents the reader is asked to read the referenced document. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_export.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_export.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_export.md @@ -0,0 +1,510 @@ + +[//000000001]: # (pt::peg::export - Parser Tools) +[//000000002]: # (Generated from file 'pt_peg_export.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::export(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::export - PEG Export + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Package commands](#subsection1) + + - [Object command](#subsection2) + + - [Object methods](#subsection3) + + - [PEG serialization format](#section3) + + - [Example](#subsection4) + + - [PE serialization format](#section4) + + - [Example](#subsection5) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit +package require configuration +package require pt::peg +package require pluginmgr +package require pt::peg::export ?1? + +[__::pt::peg::export__ *objectName*](#1) +[__objectName__ __method__ ?*arg arg ...*?](#2) +[*objectName* __destroy__](#3) +[*objectName* __export serial__ *serial* ?*format*?](#4) +[*objectName* __export object__ *object* ?*format*?](#5) +[*objectName* __configuration names__](#6) +[*objectName* __configuration get__](#7) +[*objectName* __configuration set__ *name* ?*value*?](#8) +[*objectName* __configuration unset__ *pattern*...](#9) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides a manager for parsing expression grammars, with each +instance handling a set of plugins for the export of them to other formats, i.e. +their conversion to, for example *[nroff](../../../../index.md#nroff)*, +*[HTML](../../../../index.md#html)*, etc. + +It resides in the Export section of the Core Layer of Parser Tools, and is one +of the three pillars the management of parsing expression grammars resides on. + +![](../../../../image/arch_core_export.png) The other two pillars are, as shown +above + + 1. *[PEG Import](pt_peg_import.md)*, and + + 1. *[PEG Storage](pt_peg_container.md)* + +For information about the data structure which is the major input to the manager +objects provided by this package see the section [PEG serialization +format](#section3). + +The plugin system of this class is based on the package +__[pluginmgr](../pluginmgr/pluginmgr.md)__, and configured to look for plugins +using + + 1. the environment variable __GRAMMAR_PEG_EXPORT_PLUGINS__, + + 1. the environment variable __GRAMMAR_PEG_PLUGINS__, + + 1. the environment variable __GRAMMAR_PLUGINS__, + + 1. the path "~/.grammar/peg/export/plugin" + + 1. the path "~/.grammar/peg/plugin" + + 1. the path "~/.grammar/plugin" + + 1. the path "~/.grammar/peg/export/plugins" + + 1. the path "~/.grammar/peg/plugins" + + 1. the path "~/.grammar/plugins" + + 1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\EXPORT\PLUGINS" + + 1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\PLUGINS" + + 1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PLUGINS" + +The last three are used only when the package is run on a machine using the +Windows(tm) operating system. + +The whole system is delivered with three predefined export plugins, namely + + - container + + See *PEG Export Plugin. To CONTAINER format* for details. + + - json + + See *PEG Export Plugin. To JSON format* for details. + + - peg + + See *PEG Export Plugin. To PEG format* for details. + +For readers wishing to write their own export plugin for some format, i.e. +*plugin writer*s, reading and understanding the *[Parser Tools Export +API](pt_to_api.md)* specification is an absolute necessity, as it documents the +interaction between this package and its plugins in detail. + +# API + +## Package commands + + - __::pt::peg::export__ *objectName* + + This command creates a new export manager object with an associated Tcl + command whose name is *objectName*. This + *[object](../../../../index.md#object)* command is explained in full detail + in the sections [Object command](#subsection2) and [Object + methods](#subsection3). The object command will be created under the current + namespace if the *objectName* is not fully qualified, and in the specified + namespace otherwise. + +## Object command + +All objects created by the __::pt::peg::export__ command have the following +general form: + + - __objectName__ __method__ ?*arg arg ...*? + + The method __method__ and its *arg*'uments determine the exact behavior of + the command. See section [Object methods](#subsection3) for the detailed + specifications. + +## Object methods + + - *objectName* __destroy__ + + This method destroys the object it is invoked for. + + - *objectName* __export serial__ *serial* ?*format*? + + This method takes the canonical serialization of a parsing expression + grammar stored in *serial* and converts it to the specified *format*, using + the export plugin for the format. This will fail with an error if no plugin + could be found for the format. The string generated by the conversion + process is returned as the result of this method. + + If no format is specified the method defaults to __text__. + + The specification of what a *canonical* serialization is can be found in the + section [PEG serialization format](#section3). + + The plugin has to conform to the interface documented in the *[Parser Tools + Export API](pt_to_api.md)* specification. + + - *objectName* __export object__ *object* ?*format*? + + This method is a convenient wrapper around the __export serial__ method + described by the previous item. It expects that *object* is an object + command supporting a __serialize__ method returning the canonical + serialization of a parsing expression grammar. It invokes that method, feeds + the result into __export serial__ and returns the resulting string as its + own result. + + - *objectName* __configuration names__ + + This method returns a list containing the names of all configuration options + currently known to the object. + + - *objectName* __configuration get__ + + This method returns a dictionary containing the names and values of all + configuration options currently known to the object. + + - *objectName* __configuration set__ *name* ?*value*? + + This method sets the configuration option *name* to the specified *value* + and returns the new value of the option. + + If no value is specified it simply returns the current value, without + changing it. + + Note that these configuration options and their values are simply passed to + a plugin when the actual export is performed. It is the plugin which checks + the validity, not the manager. + + - *objectName* __configuration unset__ *pattern*... + + This method unsets all configuration options matching the specified glob + *pattern*s. If no pattern is specified it will unset all currently defined + configuration options. + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section4). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section4). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_export_container.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_export_container.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_export_container.md @@ -0,0 +1,516 @@ + +[//000000001]: # (pt::peg::export::container - Parser Tools) +[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::export::container(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::export::container - PEG Export Plugin. Write CONTAINER format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Configuration](#section3) + + - [Grammar Container](#section4) + + - [Example](#subsection1) + + - [PEG serialization format](#section5) + + - [Example](#subsection2) + + - [PE serialization format](#section6) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::export::container ?1? +package require pt::peg::to::container + +[__[export](../../../../index.md#export)__ *serial* *configuration*](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the parsing expression grammar export plugin for the +generation of CONTAINER markup. + +It resides in the Export section of the Core Layer of Parser Tools and is +intended to be used by __[pt::peg::export](pt_peg_export.md)__, the export +manager, sitting between it and the corresponding core conversion functionality +provided by __[pt::peg::to::container](pt_peg_to_container.md)__. + +![](../../../../image/arch_core_eplugins.png) + +While the direct use of this package with a regular interpreter is possible, +this is strongly disrecommended and requires a number of contortions to provide +the expected environment. The proper way to use this functionality depends on +the situation: + + 1. In an untrusted environment the proper access is through the package + __[pt::peg::export](pt_peg_export.md)__ and the export manager objects it + provides. + + 1. In a trusted environment however simply use the package + __[pt::peg::to::container](pt_peg_to_container.md)__ and access the core + conversion functionality directly. + +# API + +The API provided by this package satisfies the specification of the Plugin API +found in the *[Parser Tools Export API](pt_to_api.md)* specification. + + - __[export](../../../../index.md#export)__ *serial* *configuration* + + This command takes the canonical serialization of a parsing expression + grammar, as specified in section [PEG serialization format](#section5), and + contained in *serial*, the *configuration*, a dictionary, and generates + CONTAINER markup encoding the grammar. The created string is then returned + as the result of the command. + +# Configuration + +The CONTAINER export plugin recognizes the following configuration variables and +changes its behaviour as they specify. + + - enum *mode* + + The value of this configuration variable controls which methods of + __[pt::peg](pt_pegrammar.md)__ instances the plugin will use to specify the + grammar. There are two legal values + + * __bulk__ + + In this mode the methods __start__, __add__, __modes__, and __rules__ + are used to specify the grammar in a bulk manner, i.e. as a set of + nonterminal symbols, and two dictionaries mapping from the symbols to + their semantic modes and parsing expressions. + + This mode is the default. + + * __incremental__ + + In this mode the methods __start__, __add__, __mode__, and __rule__ are + used to specify the grammar piecemal, with each nonterminal having its + own block of defining commands. + + - string *template* + + If this configuration variable is set it is assumed to contain a string into + which to put the generated code and other configuration data. The various + locations are expected to be specified with the following placeholders: + + * __@user@__ + + To be replaced with the value of the configuration variable __user__. + + * __@format@__ + + To be replaced with the the constant __CONTAINER__. + + * __@file@__ + + To be replaced with the value of the configuration variable __file__. + + * __@name@__ + + To be replaced with the value of the configuration variable __name__. + + * __@mode@__ + + To be replaced with the value of the configuration variable __mode__. + + * __@code@__ + + To be replaced with the generated code. + + If this configuration variable is not set, or empty, then the plugin falls + back to a standard template, which is defined as "__@code@__". + +*Note* that this plugin may ignore the standard configuration variables +__user__, __format__, __file__, and their values, depending on the chosen +template. + +The content of the standard configuration variable __name__, if set, is used as +name of the grammar in the output. Otherwise the plugin falls back to the +default name __a_pe_grammar__. + +# Grammar Container + +The __container__ format is another form of describing parsing expression +grammars. While data in this format is executable it does not constitute a +parser for the grammar. It always has to be used in conjunction with the package +__[pt::peg::interp](pt_peg_interp.md)__, a grammar interpreter. + +The format represents grammars by a __snit::type__, i.e. class, whose instances +are API-compatible to the instances of the +__[pt::peg::container](pt_peg_container.md)__ package, and which are preloaded +with the grammar in question. + +It has no direct formal specification beyond what was said above. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +one possible CONTAINER serialization for it is + + snit::type a_pe_grammar { + constructor {} { + install myg using pt::peg::container ${selfns}::G + $myg start {n Expression} + $myg add AddOp Digit Expression Factor MulOp Number Sign Term + $myg modes { + AddOp value + Digit value + Expression value + Factor value + MulOp value + Number value + Sign value + Term value + } + $myg rules { + AddOp {/ {t -} {t +}} + Digit {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} + Expression {/ {x {t \50} {n Expression} {t \51}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}} + Factor {x {n Term} {* {x {n AddOp} {n Term}}}} + MulOp {/ {t *} {t /}} + Number {x {? {n Sign}} {+ {n Digit}}} + Sign {/ {t -} {t +}} + Term {n Number} + } + return + } + + component myg + delegate method * to myg + } + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section6). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section6). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[CONTAINER](../../../../index.md#container), [EBNF](../../../../index.md#ebnf), +[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg), +[TDPL](../../../../index.md#tdpl), [context-free +languages](../../../../index.md#context_free_languages), +[export](../../../../index.md#export), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), +[plugin](../../../../index.md#plugin), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_export_json.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_export_json.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_export_json.md @@ -0,0 +1,566 @@ + +[//000000001]: # (pt::peg::export::json - Parser Tools) +[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::export::json(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::export::json - PEG Export Plugin. Write JSON format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Configuration](#section3) + + - [JSON Grammar Exchange Format](#section4) + + - [Example](#subsection1) + + - [PEG serialization format](#section5) + + - [Example](#subsection2) + + - [PE serialization format](#section6) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::export::json ?1? +package require pt::peg::to::json + +[__[export](../../../../index.md#export)__ *serial* *configuration*](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the parsing expression grammar export plugin for the +generation of JSON markup. + +It resides in the Export section of the Core Layer of Parser Tools and is +intended to be used by __[pt::peg::export](pt_peg_export.md)__, the export +manager, sitting between it and the corresponding core conversion functionality +provided by __[pt::peg::to::json](pt_peg_to_json.md)__. + +![](../../../../image/arch_core_eplugins.png) + +While the direct use of this package with a regular interpreter is possible, +this is strongly disrecommended and requires a number of contortions to provide +the expected environment. The proper way to use this functionality depends on +the situation: + + 1. In an untrusted environment the proper access is through the package + __[pt::peg::export](pt_peg_export.md)__ and the export manager objects it + provides. + + 1. In a trusted environment however simply use the package + __[pt::peg::to::json](pt_peg_to_json.md)__ and access the core conversion + functionality directly. + +# API + +The API provided by this package satisfies the specification of the Plugin API +found in the *[Parser Tools Export API](pt_to_api.md)* specification. + + - __[export](../../../../index.md#export)__ *serial* *configuration* + + This command takes the canonical serialization of a parsing expression + grammar, as specified in section [PEG serialization format](#section5), and + contained in *serial*, the *configuration*, a dictionary, and generates JSON + markup encoding the grammar. The created string is then returned as the + result of the command. + +# Configuration + +The JSON export plugin recognizes the following configuration variables and +changes its behaviour as they specify. + + - boolean *indented* + + If this flag is set the plugin will break the generated JSON code across + lines and indent it according to its inner structure, with each key of a + dictionary on a separate line. + + If this flag is not set (the default), the whole JSON object will be written + on a single line, with minimum spacing between all elements. + + - boolean *aligned* + + If this flag is set the generator ensures that the values for the keys in a + dictionary are vertically aligned with each other, for a nice table effect. + To make this work this also implies that __indented__ is set. + + If this flag is not set (the default), the output is formatted as per the + value of __indented__, without trying to align the values for dictionary + keys. + +*Note* that this plugin ignores the standard configuration variables __user__, +__format__, __file__, and __name__, and their values. + +# JSON Grammar Exchange Format + +The __json__ format for parsing expression grammars was written as a data +exchange format not bound to Tcl. It was defined to allow the exchange of +grammars with PackRat/PEG based parser generators for other languages. + +It is formally specified by the rules below: + + 1. The JSON of any PEG is a JSON object. + + 1. This object holds a single key, __pt::grammar::peg__, and its value. This + value holds the contents of the grammar. + + 1. The contents of the grammar are a JSON object holding the set of + nonterminal symbols and the starting expression. The relevant keys and + their values are + + - __rules__ + + The value is a JSON object whose keys are the names of the nonterminal + symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a JSON object itself. The relevant keys + and their values in this dictionary are + + * __is__ + + The value is a JSON string holding the Tcl serialization of + the parsing expression describing the symbols sentennial + structure, as specified in the section [PE serialization + format](#section6). + + * __mode__ + + The value is a JSON holding holding one of three values + specifying how a parser should handle the semantic value + produced by the symbol. + + + __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node for + the nonterminal itself, which has the ASTs of the symbol's + right hand side as its children. + + + __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node for + the nonterminal, without any children. Any ASTs generated + by the symbol's right hand side are discarded. + + + __void__ + + The nonterminal has no semantic value. Any ASTs generated + by the symbol's right hand side are discarded (as well). + + - __start__ + + The value is a JSON string holding the Tcl serialization of the start + parsing expression of the grammar, as specified in the section [PE + serialization format](#section6). + + 1. The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + +As an aside to the advanced reader, this is pretty much the same as the Tcl +serialization of PE grammars, as specified in section [PEG serialization +format](#section5), except that the Tcl dictionaries and lists of that format +are mapped to JSON objects and arrays. Only the parsing expressions themselves +are not translated further, but kept as JSON strings containing a nested Tcl +list, and there is no concept of canonicity for the JSON either. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +a JSON serialization for it is + + { + "pt::grammar::peg" : { + "rules" : { + "AddOp" : { + "is" : "\/ {t -} {t +}", + "mode" : "value" + }, + "Digit" : { + "is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}", + "mode" : "value" + }, + "Expression" : { + "is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}", + "mode" : "value" + }, + "Factor" : { + "is" : "x {n Term} {* {x {n AddOp} {n Term}}}", + "mode" : "value" + }, + "MulOp" : { + "is" : "\/ {t *} {t \/}", + "mode" : "value" + }, + "Number" : { + "is" : "x {? {n Sign}} {+ {n Digit}}", + "mode" : "value" + }, + "Sign" : { + "is" : "\/ {t -} {t +}", + "mode" : "value" + }, + "Term" : { + "is" : "n Number", + "mode" : "value" + } + }, + "start" : "n Expression" + } + } + +and a Tcl serialization of the same is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +The similarity of the latter to the JSON should be quite obvious. + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section6). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section6). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [JSON](../../../../index.md#json), +[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg), +[TDPL](../../../../index.md#tdpl), [context-free +languages](../../../../index.md#context_free_languages), +[export](../../../../index.md#export), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), +[plugin](../../../../index.md#plugin), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_export_peg.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_export_peg.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_export_peg.md @@ -0,0 +1,559 @@ + +[//000000001]: # (pt::peg::export::peg - Parser Tools) +[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::export::peg(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::export::peg - PEG Export Plugin. Write PEG format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Configuration](#section3) + + - [PEG Specification Language](#section4) + + - [Example](#subsection1) + + - [PEG serialization format](#section5) + + - [Example](#subsection2) + + - [PE serialization format](#section6) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::export::peg ?1? +package require pt::peg::to::peg + +[__[export](../../../../index.md#export)__ *serial* *configuration*](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the parsing expression grammar export plugin for the +generation of PEG markup. + +It resides in the Export section of the Core Layer of Parser Tools and is +intended to be used by __[pt::peg::export](pt_peg_export.md)__, the export +manager, sitting between it and the corresponding core conversion functionality +provided by __[pt::peg::to::peg](pt_peg_to_peg.md)__. + +![](../../../../image/arch_core_eplugins.png) + +While the direct use of this package with a regular interpreter is possible, +this is strongly disrecommended and requires a number of contortions to provide +the expected environment. The proper way to use this functionality depends on +the situation: + + 1. In an untrusted environment the proper access is through the package + __[pt::peg::export](pt_peg_export.md)__ and the export manager objects it + provides. + + 1. In a trusted environment however simply use the package + __[pt::peg::to::peg](pt_peg_to_peg.md)__ and access the core conversion + functionality directly. + +# API + +The API provided by this package satisfies the specification of the Plugin API +found in the *[Parser Tools Export API](pt_to_api.md)* specification. + + - __[export](../../../../index.md#export)__ *serial* *configuration* + + This command takes the canonical serialization of a parsing expression + grammar, as specified in section [PEG serialization format](#section5), and + contained in *serial*, the *configuration*, a dictionary, and generates PEG + markup encoding the grammar. The created string is then returned as the + result of the command. + +# Configuration + +The PEG export plugin recognizes the following configuration variables and +changes its behaviour as they specify. + + - string *template* + + If this configuration variable is set it is assumed to contain a string into + which to put the generated text and other configuration data. The various + locations are expected to be specified with the following placeholders: + + * __@user@__ + + To be replaced with the value of the configuration variable __user__. + + * __@format@__ + + To be replaced with the the constant __PEG__. + + * __@file@__ + + To be replaced with the value of the configuration variable __file__. + + * __@name@__ + + To be replaced with the value of the configuration variable __name__. + + * __@code@__ + + To be replaced with the generated text. + + If this configuration variable is not set, or empty, then the plugin falls + back to a standard template, which is defined as "__@code@__". + +*Note* that this plugin may ignore the standard configuration variables +__user__, __format__, __file__, and their values, depending on the chosen +template. + +The content of the standard configuration variable __name__, if set, is used as +name of the grammar in the output. Otherwise the plugin falls back to the +default name __a_pe_grammar__. + +# PEG Specification Language + +__peg__, a language for the specification of parsing expression grammars is +meant to be human readable, and writable as well, yet strict enough to allow its +processing by machine. Like any computer language. It was defined to make +writing the specification of a grammar easy, something the other formats found +in the Parser Tools do not lend themselves too. + +It is formally specified by the grammar shown below, written in itself. For a +tutorial / introduction to the language please go and read the *[PEG Language +Tutorial](pt_peg_language.md)*. + + PEG pe-grammar-for-peg (Grammar) + + # -------------------------------------------------------------------- + # Syntactical constructs + + Grammar <- WHITESPACE Header Definition* Final EOF ; + + Header <- PEG Identifier StartExpr ; + Definition <- Attribute? Identifier IS Expression SEMICOLON ; + Attribute <- (VOID / LEAF) COLON ; + Expression <- Sequence (SLASH Sequence)* ; + Sequence <- Prefix+ ; + Prefix <- (AND / NOT)? Suffix ; + Suffix <- Primary (QUESTION / STAR / PLUS)? ; + Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT + / GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER + / WORDCHAR / XDIGIT + / Identifier + / OPEN Expression CLOSE + / Literal + / Class + / DOT + ; + Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE + / DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ; + Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ; + Range <- Char TO Char / Char ; + + StartExpr <- OPEN Expression CLOSE ; + void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ; + + # -------------------------------------------------------------------- + # Lexing constructs + + Identifier <- Ident WHITESPACE ; + leaf: Ident <- ([_:] / ) ([_:] / )* ; + Char <- CharSpecial / CharOctalFull / CharOctalPart + / CharUnicode / CharUnescaped + ; + + leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ; + leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ; + leaf: CharOctalPart <- "\\" [0-7][0-7]? ; + leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; + leaf: CharUnescaped <- !"\\" . ; + + void: HexDigit <- [0-9a-fA-F] ; + + void: TO <- '-' ; + void: OPENB <- "[" ; + void: CLOSEB <- "]" ; + void: APOSTROPH <- "'" ; + void: DAPOSTROPH <- '"' ; + void: PEG <- "PEG" !([_:] / ) WHITESPACE ; + void: IS <- "<-" WHITESPACE ; + leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value. + leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals. + void: SEMICOLON <- ";" WHITESPACE ; + void: COLON <- ":" WHITESPACE ; + void: SLASH <- "/" WHITESPACE ; + leaf: AND <- "&" WHITESPACE ; + leaf: NOT <- "!" WHITESPACE ; + leaf: QUESTION <- "?" WHITESPACE ; + leaf: STAR <- "*" WHITESPACE ; + leaf: PLUS <- "+" WHITESPACE ; + void: OPEN <- "(" WHITESPACE ; + void: CLOSE <- ")" WHITESPACE ; + leaf: DOT <- "." WHITESPACE ; + + leaf: ALNUM <- "" WHITESPACE ; + leaf: ALPHA <- "" WHITESPACE ; + leaf: ASCII <- "" WHITESPACE ; + leaf: CONTROL <- "" WHITESPACE ; + leaf: DDIGIT <- "" WHITESPACE ; + leaf: DIGIT <- "" WHITESPACE ; + leaf: GRAPH <- "" WHITESPACE ; + leaf: LOWER <- "" WHITESPACE ; + leaf: PRINTABLE <- "" WHITESPACE ; + leaf: PUNCT <- "" WHITESPACE ; + leaf: SPACE <- "" WHITESPACE ; + leaf: UPPER <- "" WHITESPACE ; + leaf: WORDCHAR <- "" WHITESPACE ; + leaf: XDIGIT <- "" WHITESPACE ; + + void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ; + void: COMMENT <- '#' (!EOL .)* EOL ; + void: EOL <- "\n\r" / "\n" / "\r" ; + void: EOF <- !. ; + + # -------------------------------------------------------------------- + END; + +## Example + +Our example specifies the grammar for a basic 4-operation calculator. + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +Using higher-level features of the notation, i.e. the character classes +(predefined and custom), this example can be rewritten as + + PEG calculator (Expression) + Sign <- [-+] ; + Number <- Sign? + ; + Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; + MulOp <- [*/] ; + Factor <- Term (AddOp Term)* ; + AddOp <- [-+] ; + Term <- Number ; + END; + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section6). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section6). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[export](../../../../index.md#export), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), +[plugin](../../../../index.md#plugin), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_from_container.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_from_container.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_from_container.md @@ -0,0 +1,80 @@ + +[//000000001]: # (pt::peg::from::container - Parser Tools) +[//000000002]: # (Generated from file 'pt_peg_from_container.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::from::container(n) 0 tcllib "Parser Tools") + +# NAME + +pt::peg::from::container - PEG Conversion. From CONTAINER format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package does not exist. There is no need for it. The CONTAINER format for +parsing expression grammars is a piece of Tcl code which, then sourced, provides +a class whose instances have the grammar we wish to import loaded. Another way +of looking at this is, the CONTAINER output is its own import package. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_from_json.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_from_json.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_from_json.md @@ -0,0 +1,526 @@ + +[//000000001]: # (pt::peg::from::json - Parser Tools) +[//000000002]: # (Generated from file 'from.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::from::json(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::from::json - PEG Conversion. Read JSON format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [JSON Grammar Exchange Format](#section3) + + - [Example](#subsection1) + + - [PEG serialization format](#section4) + + - [Example](#subsection2) + + - [PE serialization format](#section5) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section6) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::from::json ?1? +package require pt::peg +package require json + +[__pt::peg::from::json__ __convert__ *text*](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the converter from JSON markup to parsing expression +grammars. + +It resides in the Import section of the Core Layer of Parser Tools, and can be +used either directly with the other packages of this layer, or indirectly +through the import manager provided by __[pt::peg::import](pt_peg_import.md)__. +The latter is intented for use in untrusted environments and done through the +corresponding import plugin __[pt::peg::import::json](pt_peg_import_json.md)__ +sitting between converter and import manager. + +![](../../../../image/arch_core_iplugins.png) + +# API + +The API provided by this package satisfies the specification of the Converter +API found in the *[Parser Tools Import API](pt_from_api.md)* specification. + + - __pt::peg::from::json__ __convert__ *text* + + This command takes the JSON markup encoding a parsing expression grammar and + contained in *text*, and generates the canonical serialization of said + grammar, as specified in section [PEG serialization format](#section4). The + created value is then returned as the result of the command. + +# JSON Grammar Exchange Format + +The __json__ format for parsing expression grammars was written as a data +exchange format not bound to Tcl. It was defined to allow the exchange of +grammars with PackRat/PEG based parser generators for other languages. + +It is formally specified by the rules below: + + 1. The JSON of any PEG is a JSON object. + + 1. This object holds a single key, __pt::grammar::peg__, and its value. This + value holds the contents of the grammar. + + 1. The contents of the grammar are a JSON object holding the set of + nonterminal symbols and the starting expression. The relevant keys and + their values are + + - __rules__ + + The value is a JSON object whose keys are the names of the nonterminal + symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a JSON object itself. The relevant keys + and their values in this dictionary are + + * __is__ + + The value is a JSON string holding the Tcl serialization of + the parsing expression describing the symbols sentennial + structure, as specified in the section [PE serialization + format](#section5). + + * __mode__ + + The value is a JSON holding holding one of three values + specifying how a parser should handle the semantic value + produced by the symbol. + + + __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node for + the nonterminal itself, which has the ASTs of the symbol's + right hand side as its children. + + + __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node for + the nonterminal, without any children. Any ASTs generated + by the symbol's right hand side are discarded. + + + __void__ + + The nonterminal has no semantic value. Any ASTs generated + by the symbol's right hand side are discarded (as well). + + - __start__ + + The value is a JSON string holding the Tcl serialization of the start + parsing expression of the grammar, as specified in the section [PE + serialization format](#section5). + + 1. The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + +As an aside to the advanced reader, this is pretty much the same as the Tcl +serialization of PE grammars, as specified in section [PEG serialization +format](#section4), except that the Tcl dictionaries and lists of that format +are mapped to JSON objects and arrays. Only the parsing expressions themselves +are not translated further, but kept as JSON strings containing a nested Tcl +list, and there is no concept of canonicity for the JSON either. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +a JSON serialization for it is + + { + "pt::grammar::peg" : { + "rules" : { + "AddOp" : { + "is" : "\/ {t -} {t +}", + "mode" : "value" + }, + "Digit" : { + "is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}", + "mode" : "value" + }, + "Expression" : { + "is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}", + "mode" : "value" + }, + "Factor" : { + "is" : "x {n Term} {* {x {n AddOp} {n Term}}}", + "mode" : "value" + }, + "MulOp" : { + "is" : "\/ {t *} {t \/}", + "mode" : "value" + }, + "Number" : { + "is" : "x {? {n Sign}} {+ {n Digit}}", + "mode" : "value" + }, + "Sign" : { + "is" : "\/ {t -} {t +}", + "mode" : "value" + }, + "Term" : { + "is" : "n Number", + "mode" : "value" + } + }, + "start" : "n Expression" + } + } + +and a Tcl serialization of the same is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +The similarity of the latter to the JSON should be quite obvious. + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section5). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section5). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [JSON](../../../../index.md#json), +[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg), +[TDPL](../../../../index.md#tdpl), [context-free +languages](../../../../index.md#context_free_languages), +[conversion](../../../../index.md#conversion), +[expression](../../../../index.md#expression), [format +conversion](../../../../index.md#format_conversion), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_from_peg.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_from_peg.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_from_peg.md @@ -0,0 +1,502 @@ + +[//000000001]: # (pt::peg::from::peg - Parser Tools) +[//000000002]: # (Generated from file 'from.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::from::peg(n) 1.0.3 tcllib "Parser Tools") + +# NAME + +pt::peg::from::peg - PEG Conversion. Read PEG format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [PEG Specification Language](#section3) + + - [Example](#subsection1) + + - [PEG serialization format](#section4) + + - [Example](#subsection2) + + - [PE serialization format](#section5) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section6) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::from::peg ?1.0.3? + +[__pt::peg::from::peg__ __convert__ *text*](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the converter from PEG markup to parsing expression +grammars. + +It resides in the Import section of the Core Layer of Parser Tools, and can be +used either directly with the other packages of this layer, or indirectly +through the import manager provided by __[pt::peg::import](pt_peg_import.md)__. +The latter is intented for use in untrusted environments and done through the +corresponding import plugin __[pt::peg::import::peg](pt_peg_import_peg.md)__ +sitting between converter and import manager. + +![](../../../../image/arch_core_iplugins.png) + +# API + +The API provided by this package satisfies the specification of the Converter +API found in the *[Parser Tools Import API](pt_from_api.md)* specification. + + - __pt::peg::from::peg__ __convert__ *text* + + This command takes the PEG markup encoding a parsing expression grammar and + contained in *text*, and generates the canonical serialization of said + grammar, as specified in section [PEG serialization format](#section4). The + created value is then returned as the result of the command. + +# PEG Specification Language + +__peg__, a language for the specification of parsing expression grammars is +meant to be human readable, and writable as well, yet strict enough to allow its +processing by machine. Like any computer language. It was defined to make +writing the specification of a grammar easy, something the other formats found +in the Parser Tools do not lend themselves too. + +It is formally specified by the grammar shown below, written in itself. For a +tutorial / introduction to the language please go and read the *[PEG Language +Tutorial](pt_peg_language.md)*. + + PEG pe-grammar-for-peg (Grammar) + + # -------------------------------------------------------------------- + # Syntactical constructs + + Grammar <- WHITESPACE Header Definition* Final EOF ; + + Header <- PEG Identifier StartExpr ; + Definition <- Attribute? Identifier IS Expression SEMICOLON ; + Attribute <- (VOID / LEAF) COLON ; + Expression <- Sequence (SLASH Sequence)* ; + Sequence <- Prefix+ ; + Prefix <- (AND / NOT)? Suffix ; + Suffix <- Primary (QUESTION / STAR / PLUS)? ; + Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT + / GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER + / WORDCHAR / XDIGIT + / Identifier + / OPEN Expression CLOSE + / Literal + / Class + / DOT + ; + Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE + / DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ; + Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ; + Range <- Char TO Char / Char ; + + StartExpr <- OPEN Expression CLOSE ; + void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ; + + # -------------------------------------------------------------------- + # Lexing constructs + + Identifier <- Ident WHITESPACE ; + leaf: Ident <- ([_:] / ) ([_:] / )* ; + Char <- CharSpecial / CharOctalFull / CharOctalPart + / CharUnicode / CharUnescaped + ; + + leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ; + leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ; + leaf: CharOctalPart <- "\\" [0-7][0-7]? ; + leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; + leaf: CharUnescaped <- !"\\" . ; + + void: HexDigit <- [0-9a-fA-F] ; + + void: TO <- '-' ; + void: OPENB <- "[" ; + void: CLOSEB <- "]" ; + void: APOSTROPH <- "'" ; + void: DAPOSTROPH <- '"' ; + void: PEG <- "PEG" !([_:] / ) WHITESPACE ; + void: IS <- "<-" WHITESPACE ; + leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value. + leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals. + void: SEMICOLON <- ";" WHITESPACE ; + void: COLON <- ":" WHITESPACE ; + void: SLASH <- "/" WHITESPACE ; + leaf: AND <- "&" WHITESPACE ; + leaf: NOT <- "!" WHITESPACE ; + leaf: QUESTION <- "?" WHITESPACE ; + leaf: STAR <- "*" WHITESPACE ; + leaf: PLUS <- "+" WHITESPACE ; + void: OPEN <- "(" WHITESPACE ; + void: CLOSE <- ")" WHITESPACE ; + leaf: DOT <- "." WHITESPACE ; + + leaf: ALNUM <- "" WHITESPACE ; + leaf: ALPHA <- "" WHITESPACE ; + leaf: ASCII <- "" WHITESPACE ; + leaf: CONTROL <- "" WHITESPACE ; + leaf: DDIGIT <- "" WHITESPACE ; + leaf: DIGIT <- "" WHITESPACE ; + leaf: GRAPH <- "" WHITESPACE ; + leaf: LOWER <- "" WHITESPACE ; + leaf: PRINTABLE <- "" WHITESPACE ; + leaf: PUNCT <- "" WHITESPACE ; + leaf: SPACE <- "" WHITESPACE ; + leaf: UPPER <- "" WHITESPACE ; + leaf: WORDCHAR <- "" WHITESPACE ; + leaf: XDIGIT <- "" WHITESPACE ; + + void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ; + void: COMMENT <- '#' (!EOL .)* EOL ; + void: EOL <- "\n\r" / "\n" / "\r" ; + void: EOF <- !. ; + + # -------------------------------------------------------------------- + END; + +## Example + +Our example specifies the grammar for a basic 4-operation calculator. + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +Using higher-level features of the notation, i.e. the character classes +(predefined and custom), this example can be rewritten as + + PEG calculator (Expression) + Sign <- [-+] ; + Number <- Sign? + ; + Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; + MulOp <- [*/] ; + Factor <- Term (AddOp Term)* ; + AddOp <- [-+] ; + Term <- Number ; + END; + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section5). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section5). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[conversion](../../../../index.md#conversion), +[expression](../../../../index.md#expression), [format +conversion](../../../../index.md#format_conversion), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_import.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_import.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_import.md @@ -0,0 +1,527 @@ + +[//000000001]: # (pt::peg::import - Parser Tools) +[//000000002]: # (Generated from file 'pt_peg_import.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::import(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::import - PEG Import + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Package commands](#subsection1) + + - [Object command](#subsection2) + + - [Object methods](#subsection3) + + - [PEG serialization format](#section3) + + - [Example](#subsection4) + + - [PE serialization format](#section4) + + - [Example](#subsection5) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit +package require configuration +package require pt::peg +package require pluginmgr +package require pt::peg::import ?1? + +[__::pt::peg::import__ *objectName*](#1) +[__objectName__ __method__ ?*arg arg ...*?](#2) +[*objectName* __destroy__](#3) +[*objectName* __import text__ *text* ?*format*?](#4) +[*objectName* __import file__ *path* ?*format*?](#5) +[*objectName* __import object text__ *object* *text* ?*format*?](#6) +[*objectName* __import object file__ *object* *path* ?*format*?](#7) +[*objectName* __includes__](#8) +[*objectName* __include add__ *path*](#9) +[*objectName* __include remove__ *path*](#10) +[*objectName* __include clear__](#11) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides a manager for parsing expression grammars, with each +instance handling a set of plugins for the import of them from other formats, +i.e. their conversion from, for example *peg*, *container*, +*[json](../../../../index.md#json)*, etc. + +It resides in the Import section of the Core Layer of Parser Tools, and is one +of the three pillars the management of parsing expression grammars resides on. + +![](../../../../image/arch_core_import.png) The other two pillars are, as shown +above + + 1. *[PEG Export](pt_peg_export.md)*, and + + 1. *[PEG Storage](pt_peg_container.md)* + +For information about the data structure which is the major output of the +manager objects provided by this package see the section [PEG serialization +format](#section3). + +The plugin system of our class is based on the package +__[pluginmgr](../pluginmgr/pluginmgr.md)__, and configured to look for plugins +using + + 1. the environment variable __GRAMMAR_PEG_IMPORT_PLUGINS__, + + 1. the environment variable __GRAMMAR_PEG_PLUGINS__, + + 1. the environment variable __GRAMMAR_PLUGINS__, + + 1. the path "~/.grammar/peg/import/plugin" + + 1. the path "~/.grammar/peg/plugin" + + 1. the path "~/.grammar/plugin" + + 1. the path "~/.grammar/peg/import/plugins" + + 1. the path "~/.grammar/peg/plugins" + + 1. the path "~/.grammar/plugins" + + 1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\IMPORT\PLUGINS" + + 1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\PLUGINS" + + 1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PLUGINS" + +The last three are used only when the package is run on a machine using the +Windows(tm) operating system. + +The whole system is delivered with three predefined import plugins, namely + + - container + + See *[PEG Import Plugin. From CONTAINER format](pt_peg_import_container.md)* + for details. + + - json + + See *PEG Import Plugin. From JSON format* for details. + + - peg + + See *PEG Import Plugin. From PEG format* for details. + +For readers wishing to write their own import plugin for some format, i.e. +*plugin writer*s, reading and understanding the *Parser Tools Impport API* +specification is an absolute necessity, as it documents the interaction between +this package and its plugins in detail. + +# API + +## Package commands + + - __::pt::peg::import__ *objectName* + + This command creates a new import manager object with an associated Tcl + command whose name is *objectName*. This + *[object](../../../../index.md#object)* command is explained in full detail + in the sections [Object command](#subsection2) and [Object + methods](#subsection3). The object command will be created under the current + namespace if the *objectName* is not fully qualified, and in the specified + namespace otherwise. + +## Object command + +All objects created by the __::pt::peg::import__ command have the following +general form: + + - __objectName__ __method__ ?*arg arg ...*? + + The method __method__ and its *arg*'uments determine the exact behavior of + the command. See section [Object methods](#subsection3) for the detailed + specifications. + +## Object methods + + - *objectName* __destroy__ + + This method destroys the object it is invoked for. + + - *objectName* __import text__ *text* ?*format*? + + This method takes the *text* and converts it from the specified *format* to + the canonical serialization of a parsing expression grammar using the import + plugin for the format. An error is thrown if no plugin could be found for + the format. The serialization generated by the conversion process is + returned as the result of this method. + + If no format is specified the method defaults to __text__. + + The specification of what a *canonical* serialization is can be found in the + section [PEG serialization format](#section3). + + The plugin has to conform to the interface documented in the *[Parser Tools + Import API](pt_from_api.md)* specification. + + - *objectName* __import file__ *path* ?*format*? + + This method is a convenient wrapper around the __import text__ method + described by the previous item. It reads the contents of the specified file + into memory, feeds the result into __import text__ and returns the resulting + serialization as its own result. + + - *objectName* __import object text__ *object* *text* ?*format*? + + This method is a convenient wrapper around the __import text__ method + described by the previous item. It expects that *object* is an object + command supporting a __deserialize__ method expecting the canonical + serialization of a parsing expression grammar. It imports the text using + __import text__ and then feeds the resulting serialization into the *object* + via __deserialize__. This method returns the empty string as it result. + + - *objectName* __import object file__ *object* *path* ?*format*? + + This method behaves like __import object text__, except that it reads the + text to convert from the specified file instead of being given it as + argument. + + - *objectName* __includes__ + + This method returns a list containing the currently specified paths to use + to search for include files when processing input. The order of paths in the + list corresponds to the order in which they are used, from first to last, + and also corresponds to the order in which they were added to the object. + + - *objectName* __include add__ *path* + + This methods adds the specified *path* to the list of paths to use to search + for include files when processing input. The path is added to the end of the + list, causing it to be searched after all previously added paths. The result + of the command is the empty string. + + The method does nothing if the path is already known. + + - *objectName* __include remove__ *path* + + This methods removes the specified *path* from the list of paths to use to + search for include files when processing input. The result of the command is + the empty string. + + The method does nothing if the path is not known. + + - *objectName* __include clear__ + + This method clears the list of paths to use to search for include files when + processing input. The result of the command is the empty string. + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section4). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section4). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_import_container.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_import_container.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_import_container.md @@ -0,0 +1,80 @@ + +[//000000001]: # (pt::peg::import::container - Parser Tools) +[//000000002]: # (Generated from file 'pt_peg_import_container.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::import::container(n) 0 tcllib "Parser Tools") + +# NAME + +pt::peg::import::container - PEG Import Plugin. From CONTAINER format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package does not exist. There is no need for it. The CONTAINER format for +parsing expression grammars is a piece of Tcl code which, then sourced, provides +a class whose instances have the grammar we wish to import loaded. Another way +of looking at this is, the CONTAINER output is its own import package. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_import_json.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_import_json.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_import_json.md @@ -0,0 +1,535 @@ + +[//000000001]: # (pt::peg::import::json - Parser Tools) +[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::import::json(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::import::json - PEG Import Plugin. Read JSON format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [JSON Grammar Exchange Format](#section3) + + - [Example](#subsection1) + + - [PEG serialization format](#section4) + + - [Example](#subsection2) + + - [PE serialization format](#section5) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section6) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::import::json ?1? +package require pt::peg::to::json + +[__[import](../../../../index.md#import)__ *text*](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the parsing expression grammar import plugin processing +JSON markup. + +It resides in the Import section of the Core Layer of Parser Tools and is +intended to be used by __[pt::peg::import](pt_peg_import.md)__, the import +manager, sitting between it and the corresponding core conversion functionality +provided by __[pt::peg::from::json](pt_peg_from_json.md)__. + +![](../../../../image/arch_core_iplugins.png) + +While the direct use of this package with a regular interpreter is possible, +this is strongly disrecommended and requires a number of contortions to provide +the expected environment. The proper way to use this functionality depends on +the situation: + + 1. In an untrusted environment the proper access is through the package + __[pt::peg::import](pt_peg_import.md)__ and the import manager objects it + provides. + + 1. In a trusted environment however simply use the package + __[pt::peg::from::json](pt_peg_from_json.md)__ and access the core + conversion functionality directly. + +# API + +The API provided by this package satisfies the specification of the Plugin API +found in the *[Parser Tools Import API](pt_from_api.md)* specification. + + - __[import](../../../../index.md#import)__ *text* + + This command takes the JSON markup encoding a parsing expression grammar and + contained in *text*, and generates the canonical serialization of said + grammar, as specified in section [PEG serialization format](#section4). The + created value is then returned as the result of the command. + +# JSON Grammar Exchange Format + +The __json__ format for parsing expression grammars was written as a data +exchange format not bound to Tcl. It was defined to allow the exchange of +grammars with PackRat/PEG based parser generators for other languages. + +It is formally specified by the rules below: + + 1. The JSON of any PEG is a JSON object. + + 1. This object holds a single key, __pt::grammar::peg__, and its value. This + value holds the contents of the grammar. + + 1. The contents of the grammar are a JSON object holding the set of + nonterminal symbols and the starting expression. The relevant keys and + their values are + + - __rules__ + + The value is a JSON object whose keys are the names of the nonterminal + symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a JSON object itself. The relevant keys + and their values in this dictionary are + + * __is__ + + The value is a JSON string holding the Tcl serialization of + the parsing expression describing the symbols sentennial + structure, as specified in the section [PE serialization + format](#section5). + + * __mode__ + + The value is a JSON holding holding one of three values + specifying how a parser should handle the semantic value + produced by the symbol. + + + __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node for + the nonterminal itself, which has the ASTs of the symbol's + right hand side as its children. + + + __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node for + the nonterminal, without any children. Any ASTs generated + by the symbol's right hand side are discarded. + + + __void__ + + The nonterminal has no semantic value. Any ASTs generated + by the symbol's right hand side are discarded (as well). + + - __start__ + + The value is a JSON string holding the Tcl serialization of the start + parsing expression of the grammar, as specified in the section [PE + serialization format](#section5). + + 1. The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + +As an aside to the advanced reader, this is pretty much the same as the Tcl +serialization of PE grammars, as specified in section [PEG serialization +format](#section4), except that the Tcl dictionaries and lists of that format +are mapped to JSON objects and arrays. Only the parsing expressions themselves +are not translated further, but kept as JSON strings containing a nested Tcl +list, and there is no concept of canonicity for the JSON either. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +a JSON serialization for it is + + { + "pt::grammar::peg" : { + "rules" : { + "AddOp" : { + "is" : "\/ {t -} {t +}", + "mode" : "value" + }, + "Digit" : { + "is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}", + "mode" : "value" + }, + "Expression" : { + "is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}", + "mode" : "value" + }, + "Factor" : { + "is" : "x {n Term} {* {x {n AddOp} {n Term}}}", + "mode" : "value" + }, + "MulOp" : { + "is" : "\/ {t *} {t \/}", + "mode" : "value" + }, + "Number" : { + "is" : "x {? {n Sign}} {+ {n Digit}}", + "mode" : "value" + }, + "Sign" : { + "is" : "\/ {t -} {t +}", + "mode" : "value" + }, + "Term" : { + "is" : "n Number", + "mode" : "value" + } + }, + "start" : "n Expression" + } + } + +and a Tcl serialization of the same is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +The similarity of the latter to the JSON should be quite obvious. + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section5). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section5). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [JSON](../../../../index.md#json), +[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg), +[TDPL](../../../../index.md#tdpl), [context-free +languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), [import](../../../../index.md#import), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), +[plugin](../../../../index.md#plugin), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_import_peg.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_import_peg.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_import_peg.md @@ -0,0 +1,513 @@ + +[//000000001]: # (pt::peg::import::peg - Parser Tools) +[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::import::peg(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::import::peg - PEG Import Plugin. Read PEG format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [PEG Specification Language](#section3) + + - [Example](#subsection1) + + - [PEG serialization format](#section4) + + - [Example](#subsection2) + + - [PE serialization format](#section5) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section6) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::import::peg ?1? +package require pt::peg::to::peg + +[__[import](../../../../index.md#import)__ *text*](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the parsing expression grammar import plugin processing +PEG markup. + +It resides in the Import section of the Core Layer of Parser Tools and is +intended to be used by __[pt::peg::import](pt_peg_import.md)__, the import +manager, sitting between it and the corresponding core conversion functionality +provided by __[pt::peg::from::peg](pt_peg_from_peg.md)__. + +![](../../../../image/arch_core_iplugins.png) + +While the direct use of this package with a regular interpreter is possible, +this is strongly disrecommended and requires a number of contortions to provide +the expected environment. The proper way to use this functionality depends on +the situation: + + 1. In an untrusted environment the proper access is through the package + __[pt::peg::import](pt_peg_import.md)__ and the import manager objects it + provides. + + 1. In a trusted environment however simply use the package + __[pt::peg::from::peg](pt_peg_from_peg.md)__ and access the core conversion + functionality directly. + +# API + +The API provided by this package satisfies the specification of the Plugin API +found in the *[Parser Tools Import API](pt_from_api.md)* specification. + + - __[import](../../../../index.md#import)__ *text* + + This command takes the PEG markup encoding a parsing expression grammar and + contained in *text*, and generates the canonical serialization of said + grammar, as specified in section [PEG serialization format](#section4). The + created value is then returned as the result of the command. + +# PEG Specification Language + +__peg__, a language for the specification of parsing expression grammars is +meant to be human readable, and writable as well, yet strict enough to allow its +processing by machine. Like any computer language. It was defined to make +writing the specification of a grammar easy, something the other formats found +in the Parser Tools do not lend themselves too. + +It is formally specified by the grammar shown below, written in itself. For a +tutorial / introduction to the language please go and read the *[PEG Language +Tutorial](pt_peg_language.md)*. + + PEG pe-grammar-for-peg (Grammar) + + # -------------------------------------------------------------------- + # Syntactical constructs + + Grammar <- WHITESPACE Header Definition* Final EOF ; + + Header <- PEG Identifier StartExpr ; + Definition <- Attribute? Identifier IS Expression SEMICOLON ; + Attribute <- (VOID / LEAF) COLON ; + Expression <- Sequence (SLASH Sequence)* ; + Sequence <- Prefix+ ; + Prefix <- (AND / NOT)? Suffix ; + Suffix <- Primary (QUESTION / STAR / PLUS)? ; + Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT + / GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER + / WORDCHAR / XDIGIT + / Identifier + / OPEN Expression CLOSE + / Literal + / Class + / DOT + ; + Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE + / DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ; + Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ; + Range <- Char TO Char / Char ; + + StartExpr <- OPEN Expression CLOSE ; + void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ; + + # -------------------------------------------------------------------- + # Lexing constructs + + Identifier <- Ident WHITESPACE ; + leaf: Ident <- ([_:] / ) ([_:] / )* ; + Char <- CharSpecial / CharOctalFull / CharOctalPart + / CharUnicode / CharUnescaped + ; + + leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ; + leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ; + leaf: CharOctalPart <- "\\" [0-7][0-7]? ; + leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; + leaf: CharUnescaped <- !"\\" . ; + + void: HexDigit <- [0-9a-fA-F] ; + + void: TO <- '-' ; + void: OPENB <- "[" ; + void: CLOSEB <- "]" ; + void: APOSTROPH <- "'" ; + void: DAPOSTROPH <- '"' ; + void: PEG <- "PEG" !([_:] / ) WHITESPACE ; + void: IS <- "<-" WHITESPACE ; + leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value. + leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals. + void: SEMICOLON <- ";" WHITESPACE ; + void: COLON <- ":" WHITESPACE ; + void: SLASH <- "/" WHITESPACE ; + leaf: AND <- "&" WHITESPACE ; + leaf: NOT <- "!" WHITESPACE ; + leaf: QUESTION <- "?" WHITESPACE ; + leaf: STAR <- "*" WHITESPACE ; + leaf: PLUS <- "+" WHITESPACE ; + void: OPEN <- "(" WHITESPACE ; + void: CLOSE <- ")" WHITESPACE ; + leaf: DOT <- "." WHITESPACE ; + + leaf: ALNUM <- "" WHITESPACE ; + leaf: ALPHA <- "" WHITESPACE ; + leaf: ASCII <- "" WHITESPACE ; + leaf: CONTROL <- "" WHITESPACE ; + leaf: DDIGIT <- "" WHITESPACE ; + leaf: DIGIT <- "" WHITESPACE ; + leaf: GRAPH <- "" WHITESPACE ; + leaf: LOWER <- "" WHITESPACE ; + leaf: PRINTABLE <- "" WHITESPACE ; + leaf: PUNCT <- "" WHITESPACE ; + leaf: SPACE <- "" WHITESPACE ; + leaf: UPPER <- "" WHITESPACE ; + leaf: WORDCHAR <- "" WHITESPACE ; + leaf: XDIGIT <- "" WHITESPACE ; + + void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ; + void: COMMENT <- '#' (!EOL .)* EOL ; + void: EOL <- "\n\r" / "\n" / "\r" ; + void: EOF <- !. ; + + # -------------------------------------------------------------------- + END; + +## Example + +Our example specifies the grammar for a basic 4-operation calculator. + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +Using higher-level features of the notation, i.e. the character classes +(predefined and custom), this example can be rewritten as + + PEG calculator (Expression) + Sign <- [-+] ; + Number <- Sign? + ; + Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; + MulOp <- [*/] ; + Factor <- Term (AddOp Term)* ; + AddOp <- [-+] ; + Term <- Number ; + END; + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section5). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section5). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), [import](../../../../index.md#import), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), +[plugin](../../../../index.md#plugin), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_interp.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_interp.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_interp.md @@ -0,0 +1,422 @@ + +[//000000001]: # (pt::peg::interp - Parser Tools) +[//000000002]: # (Generated from file 'pt_peg_interp.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::interp(n) 1.0.1 tcllib "Parser Tools") + +# NAME + +pt::peg::interp - Interpreter for parsing expression grammars + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Class API](#subsection1) + + - [Object API](#subsection2) + + - [AST serialization format](#section2) + + - [Example](#subsection3) + + - [PE serialization format](#section3) + + - [Example](#subsection4) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::interp ?1.0.1? +package require pt::rde ?1? +package require snit + +[__::pt::peg::interp__ *objectName* *grammar*](#1) +[*objectName* __use__ *grammar*](#2) +[*objectName* __destroy__](#3) +[*objectName* __parse__ *chan*](#4) +[*objectName* __parset__ *text*](#5) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides a class whose instances are Packrat parsers configurable +with a parsing expression grammar. The grammar is executed directly, i.e. +interpreted, with the underlying runtime provided by the package +__[pt::rde](pt_rdengine.md)__, basing everything on the PARAM. + +Like the supporting runtime this package resides in the Execution section of the +Core Layer of Parser Tools. + +![](../../../../image/arch_core_transform.png) + +The interpreted grammar is copied from an instance of +__[pt::peg::container](pt_peg_container.md)__, or anything providing the same +API, like the container classes created by +__[pt::peg::to::container](pt_peg_to_container.md)__ or the associated export +plugin __[pt::peg::export::container](pt_peg_export_container.md)__. + +## Class API + +The package exports the API described here. + + - __::pt::peg::interp__ *objectName* *grammar* + + The command creates a new parser object and returns the fully qualified name + of the object command as its result. The API of this object command is + described in the section [Object API](#subsection2). It may be used to + invoke various operations on the object. + + This new parser is configured for the execution of an empty PEG. To + configure the object for any other PEG use the method __use__ of the [Object + API](#subsection2). + +## Object API + +All objects created by this package provide the following methods. + + - *objectName* __use__ *grammar* + + This method configures the grammar interpreter / parser for the execution of + the PEG stored in *grammar*, an object which is API-compatible to instances + of __[pt::peg::container](pt_peg_container.md)__. The parser copies the + relevant information of the grammar, and does *not* take ownership of the + object. + + The information of any previously used grammar is overwritten. + + The result of the method the empty string. + + - *objectName* __destroy__ + + This method destroys the parser instance, releasing all claimed memory and + other resources, and deleting the instance command. + + The result of the command is the empty string. + + - *objectName* __parse__ *chan* + + This method runs the parser using the contents of *chan* as input (starting + at the current location in the channel), until parsing is not possible + anymore, either because parsing has completed, or run into a syntax error. + + Note here that the Parser Tools are based on Tcl 8.5+. In other words, the + channel argument is not restricted to files, sockets, etc. We have the full + power of *reflected channels* available. + + It should also be noted that the parser pulls the characters from the input + stream as it needs them. If a parser created by this package has to be + operated in a push aka event-driven manner it will be necessary to go to Tcl + 8.6+ and use the __[coroutine::auto](../coroutine/coro_auto.md)__ to wrap it + into a coroutine where __[read](../../../../index.md#read)__ is properly + changed for push-operation. + + Upon successful completion the command returns an abstract syntax tree as + its result. This AST is in the form specified in section [AST serialization + format](#section2). As a plain nested Tcl-list it can then be processed with + any Tcl commands the user likes, doing transformations, semantic checks, + etc. To help in this the package __[pt::ast](pt_astree.md)__ provides a set + of convenience commands for validation of the tree's basic structure, + printing it for debugging, and walking it either from the bottom up, or top + down. + + When encountering a syntax error the command will throw an error instead. + This error will be a 4-element Tcl-list, containing, in the order listed + below: + + The string __pt::rde__ identifying it as parser runtime error. + + The location of the parse error, as character offset from the beginning of + the parsed input. + + The location of parse error, now as a 2-element list containing line-number + and column in the line. + + A set of atomic parsing expressions indicating encoding the characters + and/or nonterminal symbols the parser expected to see at the location of the + parse error, but did not get. For the specification of atomic parsing + expressions please see the section [PE serialization format](#section3). + + - *objectName* __parset__ *text* + + This method runs the parser using the string in *text* as input. In all + other ways it behaves like the method __parse__, shown above. + +# AST serialization format + +Here we specify the format used by the Parser Tools to serialize Abstract Syntax +Trees (ASTs) as immutable values for transport, comparison, etc. + +Each node in an AST represents a nonterminal symbol of a grammar, and the range +of tokens/characters in the input covered by it. ASTs do not contain terminal +symbols, i.e. tokens/characters. These can be recovered from the input given a +symbol's location. + +We distinguish between *regular* and *canonical* serializations. While a tree +may have more than one regular serialization only exactly one of them will be +*canonical*. + + - Regular serialization + + The serialization of any AST is the serialization of its root node. + + The serialization of any node is a Tcl list containing at least three + elements. + + The first element is the name of the nonterminal symbol stored in the node. + + The second and third element are the locations of the first and last token + in the token stream the node represents (covers). + + Locations are provided as non-negative integer offsets from the beginning of + the token stream, with the first token found in the stream located at offset + 0 (zero). + + The end location has to be equal to or larger than the start location. + + All elements after the first three represent the children of the node, which + are themselves nodes. This means that the serializations of nodes without + children, i.e. leaf nodes, have exactly three elements. The children are + stored in the list with the leftmost child first, and the rightmost child + last. + + - Canonical serialization + + The canonical serialization of an abstract syntax tree has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this tree. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the parsing expression grammar below + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +and the input string + + 120+5 + +then a parser should deliver the abstract syntax tree below (except for +whitespace) + + set ast {Expression 0 4 + {Factor 0 4 + {Term 0 2 + {Number 0 2 + {Digit 0 0} + {Digit 1 1} + {Digit 2 2} + } + } + {AddOp 3 3} + {Term 4 4 + {Number 4 4 + {Digit 4 4} + } + } + } + } + +Or, more graphical + +![](../../../../image/expr_ast.png) + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_introduction.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_introduction.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_introduction.md @@ -0,0 +1,208 @@ + +[//000000001]: # (pt::pegrammar - Parser Tools) +[//000000002]: # (Generated from file 'pt_peg_introduction.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::pegrammar(n) 1 tcllib "Parser Tools") + +# NAME + +pt::pegrammar - Introduction to Parsing Expression Grammars + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Formal definition](#section2) + + - [References](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +Welcome to the introduction to *[Parsing Expression +Grammar](../../../../index.md#parsing_expression_grammar)*s (short: +*[PEG](../../../../index.md#peg)*), the formalism used by the Parser Tools. It +is assumed that the reader has a basic knowledge of parsing theory, i.e. +*Context-Free Grammars* (short: *[CFG](../../../../index.md#cfg)*), *languages*, +and associated terms like *[LL(k)](../../../../index.md#ll_k_)*, *LR(k)*, +*[terminal](../../../../index.md#terminal)* and *nonterminal* *symbols*, etc. We +do not intend to recapitulate such basic definitions or terms like *useful*, +*reachable*, (left/right) *recursive*, *nullable*, first/last/follow sets, etc. +Please see the [References](#section3) at the end instead if you are in need of +places and books which provide such background information. + +PEGs are formally very similar to CFGs, with terminal and nonterminal symbols, +start symbol, and rules defining the structure of each nonterminal symbol. The +main difference lies in the choice(sic!) of *choice* operators. Where CFGs use +an *unordered choice* to represent alternatives PEGs use *prioritized choice*. +Which is fancy way of saying that a parser has to try the first alternative +first and can try the other alternatives if only if it fails for the first, and +so on. + +On the CFG side this gives rise to LL(k) and LR(k) for making the choice +*deterministic* with a bounded *lookahead* of k terminal symbols, where LL is in +essence *topdown* aka *[recursive +descent](../../../../index.md#recursive_descent)* parsing, and LR *bottomup* aka +*shift reduce* parsing. + +On the PEG side we can parse input with recursive descent and *backtracking* of +failed choices, the latter of which amounts to unlimited lookahead. By +additionally recording the success or failure of nonterminals at the specific +locations they were tried at and reusing this information after backtracking we +can avoid the exponential blowup of running time usually associated with +backtracking and keep the parsing linear. The memory requirements are of course +higher due to this cache, as we are trading space for time. + +This is the basic concept behind *packrat parsers*. + +A limitation pure PEGs share with LL(k) CFGs is that *left-recursive* grammars +cannot be parsed, with the associated recursive descent parser entering an +infinite recursion. This limitation is usually overcome by extending pure PEGs +with explicit operators to specify repetition, zero or more, and one or more, +or, formally spoken, for the *kleene closure* and *positive kleene closure*. +This is what the Parser Tools are doing. + +Another extension, specific to Parser Tools, is a set of operators which map +more or less directly to various character classes built into Tcl, i.e. the +classes reachable via __string is__. + +The remainder of this document consists of the formal definition of PEGs for the +mathematically inclined, and an appendix listing references to places with more +information on PEGs specifically, and parsing in general. + +# Formal definition + +For the mathematically inclined, a Parsing Expression Grammar is a 4-tuple +(VN,VT,R,eS) where + + - VN is a set of *nonterminal symbols*, + + - VT is a set of *terminal symbols*, + + - R is a finite set of rules, where each rule is a pair (A,e), A in VN, and + *[e](../../../../index.md#e)* a *[parsing + expression](../../../../index.md#parsing_expression)*. + + - eS is a parsing expression, the *start expression*. + +Further constraints are + + - The intersection of VN and VT is empty. + + - For all A in VT exists exactly one pair (A,e) in R. In other words, R is a + function from nonterminal symbols to parsing expressions. + +Parsing expressions are inductively defined via + + - The empty string (epsilon) is a parsing expression. + + - A terminal symbol *a* is a parsing expression. + + - A nonterminal symbol *A* is a parsing expression. + + - *e1**e2* is a parsing expression for parsing expressions *e1* and *2*. This + is called *sequence*. + + - *e1*/*e2* is a parsing expression for parsing expressions *e1* and *2*. This + is called *ordered choice*. + + - *[e](../../../../index.md#e)** is a parsing expression for parsing + expression *[e](../../../../index.md#e)*. This is called *zero-or-more + repetitions*, also known as *kleene closure*. + + - *[e](../../../../index.md#e)*+ is a parsing expression for parsing + expression *[e](../../../../index.md#e)*. This is called *one-or-more + repetitions*, also known as *positive kleene closure*. + + - !*[e](../../../../index.md#e)* is a parsing expression for parsing + expression *e1*. This is called a *not lookahead predicate*. + + - &*[e](../../../../index.md#e)* is a parsing expression for parsing + expression *e1*. This is called an *and lookahead predicate*. + +PEGs are used to define a grammatical structure for streams of symbols over VT. +They are a modern phrasing of older formalisms invented by Alexander Birham. +These formalisms were called TS (TMG recognition scheme), and gTS (generalized +TS). Later they were renamed to TPDL (Top-Down Parsing Languages) and gTPDL +(generalized TPDL). + +They can be easily implemented by recursive descent parsers with backtracking. +This makes them relatives of LL(k) Context-Free Grammars. + +# References + + 1. [The Packrat Parsing and Parsing Expression Grammars + Page](http://www.pdos.lcs.mit.edu/~baford/packrat/), by Bryan Ford, + Massachusetts Institute of Technology. This is the main entry page to PEGs, + and their realization through Packrat Parsers. + + 1. [http://en.wikipedia.org/wiki/Parsing_expression_grammar](http://en.wikipedia.org/wiki/Parsing_expression_grammar) + Wikipedia's entry about Parsing Expression Grammars. + + 1. [Parsing Techniques - A Practical Guide + ](http://www.cs.vu.nl/~dick/PTAPG.html), an online book offering a clear, + accessible, and thorough discussion of many different parsing techniques + with their interrelations and applicabilities, including error recovery + techniques. + + 1. [Compilers and Compiler Generators](http://scifac.ru.ac.za/compilers/), an + online book using CoCo/R, a generator for recursive descent parsers. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_language.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_language.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_language.md @@ -0,0 +1,488 @@ + +[//000000001]: # (pt::peg_language - Parser Tools) +[//000000002]: # (Generated from file 'pt_peg_language.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg_language(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg_language - PEG Language Tutorial + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [What is it?](#section2) + + - [The elements of the language](#section3) + + - [Basic structure](#subsection1) + + - [Names](#subsection2) + + - [Rules](#subsection3) + + - [Expressions](#subsection4) + + - [Whitespace and comments](#subsection5) + + - [Nonterminal attributes](#subsection6) + + - [PEG Specification Language](#section4) + + - [Example](#subsection7) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +Welcome to the tutorial / introduction for the [PEG Specification +Language](#section4). If you are already familiar with the language we are about +to discuss, and only wish to refresh your memory you can, of course, skip ahead +to the aforementioned section and just read the full formal specification. + +# What is it? + +__peg__, a language for the specification of parsing expression grammars is +meant to be human readable, and writable as well, yet strict enough to allow its +processing by machine. Like any computer language. It was defined to make +writing the specification of a grammar easy, something the other formats found +in the Parser Tools do not lend themselves too. + +# The elements of the language + +## Basic structure + +The general outline of a textual PEG is + + PEG <> (<>) + <> + END; + +*Note*: We are using text in double angle-brackets as place-holders for things +not yet explained. + +## Names + +Names are mostly used to identify the nonterminal symbols of the grammar, i.e. +that which occurs on the left-hand side of a . The exception to that is +the name given after the keyword __PEG__ (see previous section), which is the +name of the whole grammar itself. + +The structure of a name is simple: + + 1. It begins with a letter, underscore, or colon, followed by + + 1. zero or more letters, digits, underscores, or colons. + +Or, in formal textual notation: + + ([_:] / ) ([_:] / )* + +Examples of names: + + Hello + ::world + _:submarine55_ + +Examples of text which are *not* names: + + 12 + .bogus + 0wrong + @location + +## Rules + +The main body of the text of a grammar specification is taken up by the rules. +Each rule defines the sentence structure of one nonterminal symbol. Their basic +structure is + + <> <- <> ; + +The specifies the nonterminal symbol to be defined, the +after the arrow (<-) then declares its structure. + +Note that each rule ends in a single semicolon, even the last. I.e. the +semicolon is a rule *terminator*, not a separator. + +We can have as many rules as we like, as long as we define each nonterminal +symbol at most once, and have at least one rule for each nonterminal symbol +which occured in an expression, i.e. in either the start expression of the +grammar, or the right-hande side of a rule. + +## Expressions + +The *parsing* expressions are the meat of any specification. They declare the +structure of the whole document (<>), and of all nonterminal +symbols. + +All expressions are made up out of *atomic expressions* and *operators* +combining them. We have operators for choosing between alternatives, repetition +of parts, and for look-ahead constraints. There is no explicit operator for the +sequencing (also known as *concatenation*) of parts however. This is specified +by simply placing the parts adjacent to each other. + +Here are the operators, from highest to lowest priority (i.e. strength of +binding): + + # Binary operators. + + <> <> # sequence. parse 1, then 2. + <> / <> # alternative. try to parse 1, and parse 2 if 1 failed to parse. + + # Prefix operators. Lookahead constraints. Same priority. + + & <> # Parse expression, ok on successful parse. + ! <> # Ditto, except ok on failure to parse. + + # Suffix operators. Repetition. Same priority. + + <> ? # Parse expression none, or once (repeat 0 or 1). + <> * # Parse expression zero or more times. + <> + # Parse expression one or more times. + + # Expression nesting + + ( <> ) # Put an expression in parens to change its priority. + +With this we can now deconstruct the formal expression for names given in +section [Names](#subsection2): + + ([_:] / ) ([_:] / )* + +It is a sequence of two parts, + + [_:] / + +and + + ([_:] / )* + +The parentheses around the parts kept their inner alternatives bound together +against the normally higher priority of the sequence. Each of the two parts is +an alternative, with the second part additionally repeated zero or more times, +leaving us with the three atomic expressions + + [_:] + + + +And *atomic expressions* are our next topic. They fall into three classes: + + 1. names, i.e. nonterminal symbols, + + 1. string literals, and + + 1. character classes. + +Names we know about already, or see section [Names](#subsection2) for a +refresher. + +String literals are simple. They are delimited by (i.e. start and end with) +either a single or double-apostroph, and in between the delimiters we can have +any character but the delimiter itself. They can be empty as well. Examples of +strings are + + '' + "" + 'hello' + "umbra" + "'" + '"' + +The last two examples show how to place any of the delimiters into a string. + +For the last, but not least of our atomic expressions, character classes, we +have a number of predefined classes, shown below, and the ability to construct +or own. The predefined classes are: + + # Any unicode alphabet or digit character (string is alnum). + # Any unicode alphabet character (string is alpha). + # Any unicode character below codepoint 0x80 (string is ascii). + # Any unicode control character (string is control). + # The digit characters [0-9]. + # Any unicode digit character (string is digit). + # Any unicode printing character, except space (string is graph). + # Any unicode lower-case alphabet character (string is lower). + # Any unicode printing character, incl. space (string is print). + # Any unicode punctuation character (string is punct). + # Any unicode space character (string is space). + # Any unicode upper-case alphabet character (string is upper). + # Any unicode word character (string is wordchar). + # The hexadecimal digit characters [0-9a-fA-F]. + . # Any character, except end of input. + +And the syntax of custom-defined character classes is + + [ <>* ] + +where each range is either a single character, or of the form + + <> - > + +Examples for character classes we have seen already in the course of this +introduction are + + [_:] + [0-9] + [0-9a-fA-F] + +We are nearly done with expressions. The only piece left is to tell how the +characters in character classes and string literals are specified. + +Basically characters in the input stand for themselves, and in addition to that +we several types of escape syntax to to repesent control characters, or +characters outside of the encoding the text is in. + +All the escaped forms are started with a backslash character ('\', unicode +codepoint 0x5C). This is then followed by a series of octal digits, or 'u' and +hexedecimal digits, or a regular character from a fixed set for various control +characters. Some examples: + + \n \r \t \' \" \[ \] \\ # + \000 up to \277 # octal escape, all ascii character, leading 0's can be removed. + \u2CA7 # hexadecimal escape, all unicode characters. + # # Here 2ca7 <=> Koptic Small Letter Tau + +## Whitespace and comments + +One issue not touched upon so far is whitespace and comments. + +Whitespace is any unicode space character, i.e. anything in the character class +, and comments. The latter are sequences of characters starting with a +'#' (hash, unicode codepoint 0x23) and ending at the next end-of-line. + +Whitespace can be freely used between all syntactical elements of a grammar +specification. It cannot be used inside of syntactical elements, like names, +string literals, predefined character classes, etc. + +## Nonterminal attributes + +Lastly, a more advanced topic. In the section [Rules](#subsection3) we gave the +structure of a rule as + + <> <- <> ; + +This is not quite true. It is possible to associate a semantic mode with the +nonterminal in the rule, by writing it before the name, separated from it by a +colon, i.e. writing + + <> : <> <- <> ; + +is also allowed. This mode is optional. The known modes and their meanings are: + + - __value__ + + The semantic value of the nonterminal symbol is an abstract syntax tree + consisting of a single node node for the nonterminal itself, which has the + ASTs of the symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an abstract syntax tree + consisting of a single node node for the nonterminal, without any children. + Any ASTs generated by the symbol's right hand side are discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs generated by the symbol's + right hand side are discarded (as well). + +Of these three modes only __leaf__ and __void__ can be specified directly. +__value__ is implicitly specified by the absence of a mode before the +nonterminal. + +Now, with all the above under our belt it should be possible to not only read, +but understand the formal specification of the text representation shown in the +next section, written in itself. + +# PEG Specification Language + +__peg__, a language for the specification of parsing expression grammars is +meant to be human readable, and writable as well, yet strict enough to allow its +processing by machine. Like any computer language. It was defined to make +writing the specification of a grammar easy, something the other formats found +in the Parser Tools do not lend themselves too. + +It is formally specified by the grammar shown below, written in itself. For a +tutorial / introduction to the language please go and read the *PEG Language +Tutorial*. + + PEG pe-grammar-for-peg (Grammar) + + # -------------------------------------------------------------------- + # Syntactical constructs + + Grammar <- WHITESPACE Header Definition* Final EOF ; + + Header <- PEG Identifier StartExpr ; + Definition <- Attribute? Identifier IS Expression SEMICOLON ; + Attribute <- (VOID / LEAF) COLON ; + Expression <- Sequence (SLASH Sequence)* ; + Sequence <- Prefix+ ; + Prefix <- (AND / NOT)? Suffix ; + Suffix <- Primary (QUESTION / STAR / PLUS)? ; + Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT + / GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER + / WORDCHAR / XDIGIT + / Identifier + / OPEN Expression CLOSE + / Literal + / Class + / DOT + ; + Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE + / DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ; + Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ; + Range <- Char TO Char / Char ; + + StartExpr <- OPEN Expression CLOSE ; + void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ; + + # -------------------------------------------------------------------- + # Lexing constructs + + Identifier <- Ident WHITESPACE ; + leaf: Ident <- ([_:] / ) ([_:] / )* ; + Char <- CharSpecial / CharOctalFull / CharOctalPart + / CharUnicode / CharUnescaped + ; + + leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ; + leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ; + leaf: CharOctalPart <- "\\" [0-7][0-7]? ; + leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; + leaf: CharUnescaped <- !"\\" . ; + + void: HexDigit <- [0-9a-fA-F] ; + + void: TO <- '-' ; + void: OPENB <- "[" ; + void: CLOSEB <- "]" ; + void: APOSTROPH <- "'" ; + void: DAPOSTROPH <- '"' ; + void: PEG <- "PEG" !([_:] / ) WHITESPACE ; + void: IS <- "<-" WHITESPACE ; + leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value. + leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals. + void: SEMICOLON <- ";" WHITESPACE ; + void: COLON <- ":" WHITESPACE ; + void: SLASH <- "/" WHITESPACE ; + leaf: AND <- "&" WHITESPACE ; + leaf: NOT <- "!" WHITESPACE ; + leaf: QUESTION <- "?" WHITESPACE ; + leaf: STAR <- "*" WHITESPACE ; + leaf: PLUS <- "+" WHITESPACE ; + void: OPEN <- "(" WHITESPACE ; + void: CLOSE <- ")" WHITESPACE ; + leaf: DOT <- "." WHITESPACE ; + + leaf: ALNUM <- "" WHITESPACE ; + leaf: ALPHA <- "" WHITESPACE ; + leaf: ASCII <- "" WHITESPACE ; + leaf: CONTROL <- "" WHITESPACE ; + leaf: DDIGIT <- "" WHITESPACE ; + leaf: DIGIT <- "" WHITESPACE ; + leaf: GRAPH <- "" WHITESPACE ; + leaf: LOWER <- "" WHITESPACE ; + leaf: PRINTABLE <- "" WHITESPACE ; + leaf: PUNCT <- "" WHITESPACE ; + leaf: SPACE <- "" WHITESPACE ; + leaf: UPPER <- "" WHITESPACE ; + leaf: WORDCHAR <- "" WHITESPACE ; + leaf: XDIGIT <- "" WHITESPACE ; + + void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ; + void: COMMENT <- '#' (!EOL .)* EOL ; + void: EOL <- "\n\r" / "\n" / "\r" ; + void: EOF <- !. ; + + # -------------------------------------------------------------------- + END; + +## Example + +Our example specifies the grammar for a basic 4-operation calculator. + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +Using higher-level features of the notation, i.e. the character classes +(predefined and custom), this example can be rewritten as + + PEG calculator (Expression) + Sign <- [-+] ; + Number <- Sign? + ; + Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; + MulOp <- [*/] ; + Factor <- Term (AddOp Term)* ; + AddOp <- [-+] ; + Term <- Number ; + END; + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_op.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_op.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_op.md @@ -0,0 +1,240 @@ + +[//000000001]: # (pt_peg_op - Parser Tools) +[//000000002]: # (Generated from file 'pt_peg_op.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt_peg_op(i) 1.1.0 tcllib "Parser Tools") + +# NAME + +pt_peg_op - Parser Tools PE Grammar Utility Operations + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::op ?1.1.0? + +[__::peg::peg::op__ __called__ *container*](#1) +[__::peg::peg::op__ __dechain__ *container*](#2) +[__::peg::peg::op__ __drop unreachable__ *container*](#3) +[__::peg::peg::op__ __drop unrealizable__ *container*](#4) +[__::peg::peg::op__ __flatten__ *container*](#5) +[__::peg::peg::op__ __minimize__ *container*](#6) +[__::peg::peg::op__ __modeopt__ *container*](#7) +[__::peg::peg::op__ __reachable__ *container*](#8) +[__::peg::peg::op__ __realizable__ *container*](#9) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides a number of utility commands manipulating a PE grammar +(container) in various ways. + +# API + + - __::peg::peg::op__ __called__ *container* + + This command determines the static call structure for the nonterminal + symbols of the grammar stored in the *container*. + + The result of the command is a dictionary mapping from each symbol to the + symbols it calls. The empty string is the key used to represent the start + expression of the grammar. + + The grammar in the container is not modified. + + The *container* instance has to expose a method API as is provided by the + package __[pt::peg::container](pt_peg_container.md)__. + + - __::peg::peg::op__ __dechain__ *container* + + This command simplifies all symbols which just chain to a different symbol + by inlining the right hand side of the called symbol in its callers. This + works if and only the modes match properly, per the decision table below. + + caller called | dechain | notes + --------------+---------+----------------------- + value value | yes | value is passed + value leaf | yes | value is passed + value void | yes | caller is implied void + leaf value | no | generated value was discarded, inlined would not. called may be implied void. + leaf leaf | no | s.a. + leaf void | no | s.a. + void value | no | caller drops value, inlined would not. + void leaf | no | s.a. + void void | yes | + + The result of the command is the empty string. + + The grammar in the container is directly modified. If that is not wanted, a + copy of the original container has to be used. + + The *container* instance has to expose a method API as is provided by the + package __[pt::peg::container](pt_peg_container.md)__. + + - __::peg::peg::op__ __drop unreachable__ *container* + + This command removes all symbols from the grammar which are not + __reachable__. + + The result of the command is the empty string. + + The grammar in the container is directly modified. If that is not wanted, a + copy of the original container has to be used. + + The *container* instance has to expose a method API as is provided by the + package __[pt::peg::container](pt_peg_container.md)__. + + - __::peg::peg::op__ __drop unrealizable__ *container* + + This command removes all symbols from the grammar which are not + __realizable__. + + The result of the command is the empty string. + + The grammar in the container is directly modified. If that is not wanted, a + copy of the original container has to be used. + + The *container* instance has to expose a method API as is provided by the + package __[pt::peg::container](pt_peg_container.md)__. + + - __::peg::peg::op__ __flatten__ *container* + + This command flattens (see __[pt::pe::op](pt_pexpr_op.md)__) all expressions + in the grammar, i.e. the start expression and the right hand sides of all + nonterminal symbols. + + The result of the command is the empty string. + + The grammar in the container is directly modified. If that is not wanted, a + copy of the original container has to be used. + + The *container* instance has to expose a method API as is provided by the + package __[pt::peg::container](pt_peg_container.md)__. + + - __::peg::peg::op__ __minimize__ *container* + + This command reduces the provided grammar by applying most of the other + methods of this package. + + After flattening the expressions it removes unreachable and unrealizable + symbols, flattens the expressions again, then optimizes the symbol modes + before collapsing symbol chains as much as possible. + + The result of the command is the empty string. + + The grammar in the container is directly modified. If that is not wanted, a + copy of the original container has to be used. + + The *container* instance has to expose a method API as is provided by the + package __[pt::peg::container](pt_peg_container.md)__. + + - __::peg::peg::op__ __modeopt__ *container* + + This command optimizes the semantic modes of non-terminal symbols according + to the two rules below. + + If a symbol X with mode __value__ calls no other symbols, i.e. uses only + terminal symbols in whatever combination, then this can be represented + simpler by using mode __leaf__. + + If a symbol X is only called from symbols with modes __leaf__ or __void__ + then this symbol should have mode __void__ also, as any AST it could + generate will be discarded anyway. + + The result of the command is the empty string. + + The grammar in the container is directly modified. If that is not wanted, a + copy of the original container has to be used. + + The *container* instance has to expose a method API as is provided by the + package __[pt::peg::container](pt_peg_container.md)__. + + - __::peg::peg::op__ __reachable__ *container* + + This command computes the set of all nonterminal symbols which are reachable + from the start expression of the grammar. This is essentially the transitive + closure over __called__ and the symbol's right hand sides, beginning with + the start expression. + + The result of the command is the list of reachable symbols. + + The grammar in the container is not modified. + + The *container* instance has to expose a method API as is provided by the + package __[pt::peg::container](pt_peg_container.md)__. + + - __::peg::peg::op__ __realizable__ *container* + + This command computes the set of all nonterminal symbols which are + realizable, i.e. can derive pure terminal phrases. This is done iteratively, + starting with state unrealizable for all and any, and then updating all + symbols which are realizable, propagating changes, until nothing changes any + more. + + The result of the command is the list of realizable symbols. + + The grammar in the container is not modified. + + The *container* instance has to expose a method API as is provided by the + package __[pt::peg::container](pt_peg_container.md)__. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_to_container.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_to_container.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_to_container.md @@ -0,0 +1,541 @@ + +[//000000001]: # (pt::peg::to::container - Parser Tools) +[//000000002]: # (Generated from file 'to.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::to::container(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::to::container - PEG Conversion. Write CONTAINER format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Options](#section3) + + - [Grammar Container](#section4) + + - [Example](#subsection1) + + - [PEG serialization format](#section5) + + - [Example](#subsection2) + + - [PE serialization format](#section6) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::to::container ?1? +package require pt::peg +package require text::write +package require char + +[__pt::peg::to::container__ __reset__](#1) +[__pt::peg::to::container__ __configure__](#2) +[__pt::peg::to::container__ __configure__ *option*](#3) +[__pt::peg::to::container__ __configure__ *option* *value*...](#4) +[__pt::peg::to::container__ __convert__ *serial*](#5) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the converter from parsing expression grammars to +CONTAINER markup. + +It resides in the Export section of the Core Layer of Parser Tools, and can be +used either directly with the other packages of this layer, or indirectly +through the export manager provided by __[pt::peg::export](pt_peg_export.md)__. +The latter is intented for use in untrusted environments and done through the +corresponding export plugin +__[pt::peg::export::container](pt_peg_export_container.md)__ sitting between +converter and export manager. + +![](../../../../image/arch_core_eplugins.png) + +# API + +The API provided by this package satisfies the specification of the Converter +API found in the *[Parser Tools Export API](pt_to_api.md)* specification. + + - __pt::peg::to::container__ __reset__ + + This command resets the configuration of the package to its default + settings. + + - __pt::peg::to::container__ __configure__ + + This command returns a dictionary containing the current configuration of + the package. + + - __pt::peg::to::container__ __configure__ *option* + + This command returns the current value of the specified configuration + *option* of the package. For the set of legal options, please read the + section [Options](#section3). + + - __pt::peg::to::container__ __configure__ *option* *value*... + + This command sets the given configuration *option*s of the package, to the + specified *value*s. For the set of legal options, please read the section + [Options](#section3). + + - __pt::peg::to::container__ __convert__ *serial* + + This command takes the canonical serialization of a parsing expression + grammar, as specified in section [PEG serialization format](#section5), and + contained in *serial*, and generates CONTAINER markup encoding the grammar, + per the current package configuration. The created string is then returned + as the result of the command. + +# Options + +The converter to the CONTAINER format recognizes the following options and +changes its behaviour as they specify. + + - __-file__ string + + The value of this option is the name of the file or other entity from which + the grammar came, for which the command is run. The default value is + __unknown__. + + - __-name__ string + + The value of this option is the name of the grammar we are processing. The + default value is __a_pe_grammar__. + + - __-user__ string + + The value of this option is the name of the user for which the command is + run. The default value is __unknown__. + + - __-mode__ __bulk__|__incremental__ + + The value of this option controls which methods of + __[pt::peg::container](pt_peg_container.md)__ instances are used to specify + the grammar, i.e. preload it into the container. There are two legal values, + as listed below. The default is __bulk__. + + * __bulk__ + + In this mode the methods __start__, __add__, __modes__, and __rules__ + are used to specify the grammar in a bulk manner, i.e. as a set of + nonterminal symbols, and two dictionaries mapping from the symbols to + their semantic modes and parsing expressions. + + This mode is the default. + + * __incremental__ + + In this mode the methods __start__, __add__, __mode__, and __rule__ are + used to specify the grammar piecemal, with each nonterminal having its + own block of defining commands. + + - __-template__ string + + The value of this option is a string into which to put the generated code + and the other configuration settings. The various locations for user-data + are expected to be specified with the placeholders listed below. The default + value is "__@code@__". + + * __@user@__ + + To be replaced with the value of the option __-user__. + + * __@format@__ + + To be replaced with the the constant __CONTAINER__. + + * __@file@__ + + To be replaced with the value of the option __-file__. + + * __@name@__ + + To be replaced with the value of the option __-name__. + + * __@mode@__ + + To be replaced with the value of the option __-mode__. + + * __@code@__ + + To be replaced with the generated code. + +# Grammar Container + +The __container__ format is another form of describing parsing expression +grammars. While data in this format is executable it does not constitute a +parser for the grammar. It always has to be used in conjunction with the package +__[pt::peg::interp](pt_peg_interp.md)__, a grammar interpreter. + +The format represents grammars by a __snit::type__, i.e. class, whose instances +are API-compatible to the instances of the +__[pt::peg::container](pt_peg_container.md)__ package, and which are preloaded +with the grammar in question. + +It has no direct formal specification beyond what was said above. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +one possible CONTAINER serialization for it is + + snit::type a_pe_grammar { + constructor {} { + install myg using pt::peg::container ${selfns}::G + $myg start {n Expression} + $myg add AddOp Digit Expression Factor MulOp Number Sign Term + $myg modes { + AddOp value + Digit value + Expression value + Factor value + MulOp value + Number value + Sign value + Term value + } + $myg rules { + AddOp {/ {t -} {t +}} + Digit {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} + Expression {/ {x {t \50} {n Expression} {t \51}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}} + Factor {x {n Term} {* {x {n AddOp} {n Term}}}} + MulOp {/ {t *} {t /}} + Number {x {? {n Sign}} {+ {n Digit}}} + Sign {/ {t -} {t +}} + Term {n Number} + } + return + } + + component myg + delegate method * to myg + } + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section6). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section6). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[CONTAINER](../../../../index.md#container), [EBNF](../../../../index.md#ebnf), +[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg), +[TDPL](../../../../index.md#tdpl), [context-free +languages](../../../../index.md#context_free_languages), +[conversion](../../../../index.md#conversion), +[expression](../../../../index.md#expression), [format +conversion](../../../../index.md#format_conversion), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_to_cparam.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_to_cparam.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_to_cparam.md @@ -0,0 +1,596 @@ + +[//000000001]: # (pt::peg::to::cparam - Parser Tools) +[//000000002]: # (Generated from file 'to.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::to::cparam(n) 1.1.2 tcllib "Parser Tools") + +# NAME + +pt::peg::to::cparam - PEG Conversion. Write CPARAM format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Options](#section3) + + - [C/PARAM code representation of parsing expression grammars](#section4) + + - [Example](#subsection1) + + - [PEG serialization format](#section5) + + - [Example](#subsection2) + + - [PE serialization format](#section6) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::to::cparam ?1.1.2? + +[__pt::peg::to::cparam__ __reset__](#1) +[__pt::peg::to::cparam__ __configure__](#2) +[__pt::peg::to::cparam__ __configure__ *option*](#3) +[__pt::peg::to::cparam__ __configure__ *option* *value*...](#4) +[__pt::peg::to::cparam__ __convert__ *serial*](#5) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the converter from parsing expression grammars to CPARAM +markup. + +It resides in the Export section of the Core Layer of Parser Tools, and can be +used either directly with the other packages of this layer, or indirectly +through the export manager provided by __[pt::peg::export](pt_peg_export.md)__. +The latter is intented for use in untrusted environments and done through the +corresponding export plugin __pt::peg::export::cparam__ sitting between +converter and export manager. + +![](../../../../image/arch_core_eplugins.png) + +# API + +The API provided by this package satisfies the specification of the Converter +API found in the *[Parser Tools Export API](pt_to_api.md)* specification. + + - __pt::peg::to::cparam__ __reset__ + + This command resets the configuration of the package to its default + settings. + + - __pt::peg::to::cparam__ __configure__ + + This command returns a dictionary containing the current configuration of + the package. + + - __pt::peg::to::cparam__ __configure__ *option* + + This command returns the current value of the specified configuration + *option* of the package. For the set of legal options, please read the + section [Options](#section3). + + - __pt::peg::to::cparam__ __configure__ *option* *value*... + + This command sets the given configuration *option*s of the package, to the + specified *value*s. For the set of legal options, please read the section + [Options](#section3). + + - __pt::peg::to::cparam__ __convert__ *serial* + + This command takes the canonical serialization of a parsing expression + grammar, as specified in section [PEG serialization format](#section5), and + contained in *serial*, and generates CPARAM markup encoding the grammar, per + the current package configuration. The created string is then returned as + the result of the command. + +# Options + +The converter to C code recognizes the following configuration variables and +changes its behaviour as they specify. + + - __-file__ string + + The value of this option is the name of the file or other entity from which + the grammar came, for which the command is run. The default value is + __unknown__. + + - __-name__ string + + The value of this option is the name of the grammar we are processing. The + default value is __a_pe_grammar__. + + - __-user__ string + + The value of this option is the name of the user for which the command is + run. The default value is __unknown__. + + - __-template__ string + + The value of this option is a string into which to put the generated text + and the other configuration settings. The various locations for user-data + are expected to be specified with the placeholders listed below. The default + value is "__@code@__". + + * __@user@__ + + To be replaced with the value of the option __-user__. + + * __@format@__ + + To be replaced with the the constant __C/PARAM__. + + * __@file@__ + + To be replaced with the value of the option __-file__. + + * __@name@__ + + To be replaced with the value of the option __-name__. + + * __@code@__ + + To be replaced with the generated Tcl code. + + The following options are special, in that they will occur within the + generated code, and are replaced there as well. + + * __@statedecl@__ + + To be replaced with the value of the option __state-decl__. + + * __@stateref@__ + + To be replaced with the value of the option __state-ref__. + + * __@strings@__ + + To be replaced with the value of the option __string-varname__. + + * __@self@__ + + To be replaced with the value of the option __self-command__. + + * __@def@__ + + To be replaced with the value of the option __fun-qualifier__. + + * __@ns@__ + + To be replaced with the value of the option __namespace__. + + * __@main@__ + + To be replaced with the value of the option __main__. + + * __@prelude@__ + + To be replaced with the value of the option __prelude__. + + - __-state-decl__ string + + A C string representing the argument declaration to use in the generated + parsing functions to refer to the parsing state. In essence type and + argument name. The default value is the string __RDE_PARAM p__. + + - __-state-ref__ string + + A C string representing the argument named used in the generated parsing + functions to refer to the parsing state. The default value is the string + __p__. + + - __-self-command__ string + + A C string representing the reference needed to call the generated parser + function (methods ...) from another parser fonction, per the chosen + framework (template). The default value is the empty string. + + - __-fun-qualifier__ string + + A C string containing the attributes to give to the generated functions + (methods ...), per the chosen framework (template). The default value is + __static__. + + - __-namespace__ string + + The name of the C namespace the parser functions (methods, ...) shall reside + in, or a general prefix to add to the function names. The default value is + the empty string. + + - __-main__ string + + The name of the main function (method, ...) to be called by the chosen + framework (template) to start parsing input. The default value is + ____main__. + + - __-string-varname__ string + + The name of the variable used for the table of strings used by the generated + parser, i.e. error messages, symbol names, etc. The default value is + __p_string__. + + - __-prelude__ string + + A snippet of code to be inserted at the head of each generated parsing + function. The default value is the empty string. + + - __-indent__ integer + + The number of characters to indent each line of the generated code by. The + default value is __0__. + + - __-comments__ boolean + + A flag controlling the generation of code comments containing the original + parsing expression a parsing function is for. The default value is __on__. + +While the high parameterizability of this converter, as shown by the multitude +of options it supports, is an advantage to the advanced user, allowing her to +customize the output of the converter as needed, a novice user will likely not +see the forest for the trees. + +To help these latter users an adjunct package is provided, containing a canned +configuration which will generate immediately useful full parsers. It is + + - __[pt::cparam::configuration::critcl](pt_cparam_config_critcl.md)__ + + Generated parsers are embedded into a __Critcl__-based framework. + +# C/PARAM code representation of parsing expression grammars + +The __c__ format is executable code, a parser for the grammar. The parser +implementation is written in C and can be tweaked to the users' needs through a +multitude of options. + +The __critcl__ format, for example, is implemented as a canned configuration of +these options on top of the generator for __c__. + +The bulk of such a framework has to be specified through the option +__-template__. The additional options + + - __-fun-qualifier__ string + + - __-main__ string + + - __-namespace__ string + + - __-prelude__ string + + - __-self-command__ string + + - __-state-decl__ string + + - __-state-ref__ string + + - __-string-varname__ string + +provide code snippets which help to glue framework and generated code together. +Their placeholders are in the *generated* code. Further the options + + - __-indent__ integer + + - __-comments__ boolean + +allow for the customization of the code indent (default none), and whether to +generate comments showing the parsing expressions a function is for (default +on). + +## Example + +We are forgoing an example of this representation, with apologies. It would be +way to large for this document. + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section6). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section6). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[CPARAM](../../../../index.md#cparam), [EBNF](../../../../index.md#ebnf), +[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg), +[TDPL](../../../../index.md#tdpl), [context-free +languages](../../../../index.md#context_free_languages), +[conversion](../../../../index.md#conversion), +[expression](../../../../index.md#expression), [format +conversion](../../../../index.md#format_conversion), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_to_json.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_to_json.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_to_json.md @@ -0,0 +1,595 @@ + +[//000000001]: # (pt::peg::to::json - Parser Tools) +[//000000002]: # (Generated from file 'to.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::to::json(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::to::json - PEG Conversion. Write JSON format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Options](#section3) + + - [JSON Grammar Exchange Format](#section4) + + - [Example](#subsection1) + + - [PEG serialization format](#section5) + + - [Example](#subsection2) + + - [PE serialization format](#section6) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::to::json ?1? +package require pt::peg +package require json::write + +[__pt::peg::to::json__ __reset__](#1) +[__pt::peg::to::json__ __configure__](#2) +[__pt::peg::to::json__ __configure__ *option*](#3) +[__pt::peg::to::json__ __configure__ *option* *value*...](#4) +[__pt::peg::to::json__ __convert__ *serial*](#5) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the converter from parsing expression grammars to JSON +markup. + +It resides in the Export section of the Core Layer of Parser Tools, and can be +used either directly with the other packages of this layer, or indirectly +through the export manager provided by __[pt::peg::export](pt_peg_export.md)__. +The latter is intented for use in untrusted environments and done through the +corresponding export plugin __[pt::peg::export::json](pt_peg_export_json.md)__ +sitting between converter and export manager. + +![](../../../../image/arch_core_eplugins.png) + +# API + +The API provided by this package satisfies the specification of the Converter +API found in the *[Parser Tools Export API](pt_to_api.md)* specification. + + - __pt::peg::to::json__ __reset__ + + This command resets the configuration of the package to its default + settings. + + - __pt::peg::to::json__ __configure__ + + This command returns a dictionary containing the current configuration of + the package. + + - __pt::peg::to::json__ __configure__ *option* + + This command returns the current value of the specified configuration + *option* of the package. For the set of legal options, please read the + section [Options](#section3). + + - __pt::peg::to::json__ __configure__ *option* *value*... + + This command sets the given configuration *option*s of the package, to the + specified *value*s. For the set of legal options, please read the section + [Options](#section3). + + - __pt::peg::to::json__ __convert__ *serial* + + This command takes the canonical serialization of a parsing expression + grammar, as specified in section [PEG serialization format](#section5), and + contained in *serial*, and generates JSON markup encoding the grammar, per + the current package configuration. The created string is then returned as + the result of the command. + +# Options + +The converter to the JSON grammar exchange format recognizes the following +configuration variables and changes its behaviour as they specify. + + - __-file__ string + + The value of this option is the name of the file or other entity from which + the grammar came, for which the command is run. The default value is + __unknown__. + + - __-name__ string + + The value of this option is the name of the grammar we are processing. The + default value is __a_pe_grammar__. + + - __-user__ string + + The value of this option is the name of the user for which the command is + run. The default value is __unknown__. + + - __-indented__ boolean + + If this option is set the system will break the generated JSON across lines + and indent it according to its inner structure, with each key of a + dictionary on a separate line. + + If the option is not set (the default), the whole JSON object will be + written on a single line, with minimum spacing between all elements. + + - __-aligned__ boolean + + If this option is set the system will ensure that the values for the keys in + a dictionary are vertically aligned with each other, for a nice table + effect. To make this work this also implies that __-indented__ is set. + + If the option is not set (the default), the output is formatted as per the + value of __indented__, without trying to align the values for dictionary + keys. + +# JSON Grammar Exchange Format + +The __json__ format for parsing expression grammars was written as a data +exchange format not bound to Tcl. It was defined to allow the exchange of +grammars with PackRat/PEG based parser generators for other languages. + +It is formally specified by the rules below: + + 1. The JSON of any PEG is a JSON object. + + 1. This object holds a single key, __pt::grammar::peg__, and its value. This + value holds the contents of the grammar. + + 1. The contents of the grammar are a JSON object holding the set of + nonterminal symbols and the starting expression. The relevant keys and + their values are + + - __rules__ + + The value is a JSON object whose keys are the names of the nonterminal + symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a JSON object itself. The relevant keys + and their values in this dictionary are + + * __is__ + + The value is a JSON string holding the Tcl serialization of + the parsing expression describing the symbols sentennial + structure, as specified in the section [PE serialization + format](#section6). + + * __mode__ + + The value is a JSON holding holding one of three values + specifying how a parser should handle the semantic value + produced by the symbol. + + + __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node for + the nonterminal itself, which has the ASTs of the symbol's + right hand side as its children. + + + __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node for + the nonterminal, without any children. Any ASTs generated + by the symbol's right hand side are discarded. + + + __void__ + + The nonterminal has no semantic value. Any ASTs generated + by the symbol's right hand side are discarded (as well). + + - __start__ + + The value is a JSON string holding the Tcl serialization of the start + parsing expression of the grammar, as specified in the section [PE + serialization format](#section6). + + 1. The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + +As an aside to the advanced reader, this is pretty much the same as the Tcl +serialization of PE grammars, as specified in section [PEG serialization +format](#section5), except that the Tcl dictionaries and lists of that format +are mapped to JSON objects and arrays. Only the parsing expressions themselves +are not translated further, but kept as JSON strings containing a nested Tcl +list, and there is no concept of canonicity for the JSON either. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +a JSON serialization for it is + + { + "pt::grammar::peg" : { + "rules" : { + "AddOp" : { + "is" : "\/ {t -} {t +}", + "mode" : "value" + }, + "Digit" : { + "is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}", + "mode" : "value" + }, + "Expression" : { + "is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}", + "mode" : "value" + }, + "Factor" : { + "is" : "x {n Term} {* {x {n AddOp} {n Term}}}", + "mode" : "value" + }, + "MulOp" : { + "is" : "\/ {t *} {t \/}", + "mode" : "value" + }, + "Number" : { + "is" : "x {? {n Sign}} {+ {n Digit}}", + "mode" : "value" + }, + "Sign" : { + "is" : "\/ {t -} {t +}", + "mode" : "value" + }, + "Term" : { + "is" : "n Number", + "mode" : "value" + } + }, + "start" : "n Expression" + } + } + +and a Tcl serialization of the same is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +The similarity of the latter to the JSON should be quite obvious. + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section6). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section6). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [JSON](../../../../index.md#json), +[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg), +[TDPL](../../../../index.md#tdpl), [context-free +languages](../../../../index.md#context_free_languages), +[conversion](../../../../index.md#conversion), +[expression](../../../../index.md#expression), [format +conversion](../../../../index.md#format_conversion), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_to_param.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_to_param.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_to_param.md @@ -0,0 +1,1238 @@ + +[//000000001]: # (pt::peg::to::param - Parser Tools) +[//000000002]: # (Generated from file 'to.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::to::param(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg::to::param - PEG Conversion. Write PARAM format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Options](#section3) + + - [PARAM code representation of parsing expression grammars](#section4) + + - [Example](#subsection1) + + - [PEG serialization format](#section5) + + - [Example](#subsection2) + + - [PE serialization format](#section6) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::to::param ?1? +package require pt::peg +package require pt::pe + +[__pt::peg::to::param__ __reset__](#1) +[__pt::peg::to::param__ __configure__](#2) +[__pt::peg::to::param__ __configure__ *option*](#3) +[__pt::peg::to::param__ __configure__ *option* *value*...](#4) +[__pt::peg::to::param__ __convert__ *serial*](#5) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the converter from parsing expression grammars to PARAM +markup. + +It resides in the Export section of the Core Layer of Parser Tools, and can be +used either directly with the other packages of this layer, or indirectly +through the export manager provided by __[pt::peg::export](pt_peg_export.md)__. +The latter is intented for use in untrusted environments and done through the +corresponding export plugin __pt::peg::export::param__ sitting between converter +and export manager. + +![](../../../../image/arch_core_eplugins.png) + +# API + +The API provided by this package satisfies the specification of the Converter +API found in the *[Parser Tools Export API](pt_to_api.md)* specification. + + - __pt::peg::to::param__ __reset__ + + This command resets the configuration of the package to its default + settings. + + - __pt::peg::to::param__ __configure__ + + This command returns a dictionary containing the current configuration of + the package. + + - __pt::peg::to::param__ __configure__ *option* + + This command returns the current value of the specified configuration + *option* of the package. For the set of legal options, please read the + section [Options](#section3). + + - __pt::peg::to::param__ __configure__ *option* *value*... + + This command sets the given configuration *option*s of the package, to the + specified *value*s. For the set of legal options, please read the section + [Options](#section3). + + - __pt::peg::to::param__ __convert__ *serial* + + This command takes the canonical serialization of a parsing expression + grammar, as specified in section [PEG serialization format](#section5), and + contained in *serial*, and generates PARAM markup encoding the grammar, per + the current package configuration. The created string is then returned as + the result of the command. + +# Options + +The converter to PARAM markup recognizes the following configuration variables +and changes its behaviour as they specify. + + - __-template__ string + + The value of this configuration variable is a string into which to put the + generated text and the other configuration settings. The various locations + for user-data are expected to be specified with the placeholders listed + below. The default value is "__@code@__". + + * __@user@__ + + To be replaced with the value of the configuration variable __-user__. + + * __@format@__ + + To be replaced with the the constant __PARAM__. + + * __@file@__ + + To be replaced with the value of the configuration variable __-file__. + + * __@name@__ + + To be replaced with the value of the configuration variable __-name__. + + * __@code@__ + + To be replaced with the generated text. + + - __-name__ string + + The value of this configuration variable is the name of the grammar for + which the conversion is run. The default value is __a_pe_grammar__. + + - __-user__ string + + The value of this configuration variable is the name of the user for which + the conversion is run. The default value is __unknown__. + + - __-file__ string + + The value of this configuration variable is the name of the file or other + entity from which the grammar came, for which the conversion is run. The + default value is __unknown__. + +# PARAM code representation of parsing expression grammars + +The PARAM code representation of parsing expression grammars is assembler-like +text using the instructions of the virtual machine documented in the *[PackRat +Machine Specification](pt_param.md)*, plus a few more for control flow (jump ok, +jump fail, call symbol, return). + +It is not really useful, except possibly as a tool demonstrating how a grammar +is compiled in general, without getting distracted by the incidentials of a +framework, i.e. like the supporting C and Tcl code generated by the other +PARAM-derived formats. + +It has no direct formal specification beyond what was said above. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +one possible PARAM serialization for it is + + # -*- text -*- + # Parsing Expression Grammar 'TEMPLATE'. + # Generated for unknown, from file 'TEST' + + # + # Grammar Start Expression + # + + <

>: + call sym_Expression + halt + + # + # value Symbol 'AddOp' + # + + sym_AddOp: + # / + # '-' + # '+' + + symbol_restore AddOp + found! jump found_7 + loc_push + + call choice_5 + + fail! value_clear + ok! value_leaf AddOp + symbol_save AddOp + error_nonterminal AddOp + loc_pop_discard + + found_7: + ok! ast_value_push + return + + choice_5: + # / + # '-' + # '+' + + error_clear + + loc_push + error_push + + input_next "t -" + ok! test_char "-" + + error_pop_merge + ok! jump oknoast_4 + + loc_pop_rewind + loc_push + error_push + + input_next "t +" + ok! test_char "+" + + error_pop_merge + ok! jump oknoast_4 + + loc_pop_rewind + status_fail + return + + oknoast_4: + loc_pop_discard + return + # + # value Symbol 'Digit' + # + + sym_Digit: + # / + # '0' + # '1' + # '2' + # '3' + # '4' + # '5' + # '6' + # '7' + # '8' + # '9' + + symbol_restore Digit + found! jump found_22 + loc_push + + call choice_20 + + fail! value_clear + ok! value_leaf Digit + symbol_save Digit + error_nonterminal Digit + loc_pop_discard + + found_22: + ok! ast_value_push + return + + choice_20: + # / + # '0' + # '1' + # '2' + # '3' + # '4' + # '5' + # '6' + # '7' + # '8' + # '9' + + error_clear + + loc_push + error_push + + input_next "t 0" + ok! test_char "0" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 1" + ok! test_char "1" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 2" + ok! test_char "2" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 3" + ok! test_char "3" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 4" + ok! test_char "4" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 5" + ok! test_char "5" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 6" + ok! test_char "6" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 7" + ok! test_char "7" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 8" + ok! test_char "8" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 9" + ok! test_char "9" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + status_fail + return + + oknoast_19: + loc_pop_discard + return + # + # value Symbol 'Expression' + # + + sym_Expression: + # / + # x + # '$' + # (Expression) + # '$' + # x + # (Factor) + # * + # x + # (MulOp) + # (Factor) + + symbol_restore Expression + found! jump found_46 + loc_push + ast_push + + call choice_44 + + fail! value_clear + ok! value_reduce Expression + symbol_save Expression + error_nonterminal Expression + ast_pop_rewind + loc_pop_discard + + found_46: + ok! ast_value_push + return + + choice_44: + # / + # x + # '$' + # (Expression) + # '$' + # x + # (Factor) + # * + # x + # (MulOp) + # (Factor) + + error_clear + + ast_push + loc_push + error_push + + call sequence_27 + + error_pop_merge + ok! jump ok_43 + + ast_pop_rewind + loc_pop_rewind + ast_push + loc_push + error_push + + call sequence_40 + + error_pop_merge + ok! jump ok_43 + + ast_pop_rewind + loc_pop_rewind + status_fail + return + + ok_43: + ast_pop_discard + loc_pop_discard + return + + sequence_27: + # x + # '$' + # (Expression) + # '$' + + loc_push + error_clear + + error_push + + input_next "t (" + ok! test_char "(" + + error_pop_merge + fail! jump failednoast_29 + ast_push + error_push + + call sym_Expression + + error_pop_merge + fail! jump failed_28 + error_push + + input_next "t )" + ok! test_char ")" + + error_pop_merge + fail! jump failed_28 + + ast_pop_discard + loc_pop_discard + return + + failed_28: + ast_pop_rewind + + failednoast_29: + loc_pop_rewind + return + + sequence_40: + # x + # (Factor) + # * + # x + # (MulOp) + # (Factor) + + ast_push + loc_push + error_clear + + error_push + + call sym_Factor + + error_pop_merge + fail! jump failed_41 + error_push + + call kleene_37 + + error_pop_merge + fail! jump failed_41 + + ast_pop_discard + loc_pop_discard + return + + failed_41: + ast_pop_rewind + loc_pop_rewind + return + + kleene_37: + # * + # x + # (MulOp) + # (Factor) + + loc_push + error_push + + call sequence_34 + + error_pop_merge + fail! jump failed_38 + loc_pop_discard + jump kleene_37 + + failed_38: + loc_pop_rewind + status_ok + return + + sequence_34: + # x + # (MulOp) + # (Factor) + + ast_push + loc_push + error_clear + + error_push + + call sym_MulOp + + error_pop_merge + fail! jump failed_35 + error_push + + call sym_Factor + + error_pop_merge + fail! jump failed_35 + + ast_pop_discard + loc_pop_discard + return + + failed_35: + ast_pop_rewind + loc_pop_rewind + return + # + # value Symbol 'Factor' + # + + sym_Factor: + # x + # (Term) + # * + # x + # (AddOp) + # (Term) + + symbol_restore Factor + found! jump found_60 + loc_push + ast_push + + call sequence_57 + + fail! value_clear + ok! value_reduce Factor + symbol_save Factor + error_nonterminal Factor + ast_pop_rewind + loc_pop_discard + + found_60: + ok! ast_value_push + return + + sequence_57: + # x + # (Term) + # * + # x + # (AddOp) + # (Term) + + ast_push + loc_push + error_clear + + error_push + + call sym_Term + + error_pop_merge + fail! jump failed_58 + error_push + + call kleene_54 + + error_pop_merge + fail! jump failed_58 + + ast_pop_discard + loc_pop_discard + return + + failed_58: + ast_pop_rewind + loc_pop_rewind + return + + kleene_54: + # * + # x + # (AddOp) + # (Term) + + loc_push + error_push + + call sequence_51 + + error_pop_merge + fail! jump failed_55 + loc_pop_discard + jump kleene_54 + + failed_55: + loc_pop_rewind + status_ok + return + + sequence_51: + # x + # (AddOp) + # (Term) + + ast_push + loc_push + error_clear + + error_push + + call sym_AddOp + + error_pop_merge + fail! jump failed_52 + error_push + + call sym_Term + + error_pop_merge + fail! jump failed_52 + + ast_pop_discard + loc_pop_discard + return + + failed_52: + ast_pop_rewind + loc_pop_rewind + return + # + # value Symbol 'MulOp' + # + + sym_MulOp: + # / + # '*' + # '/' + + symbol_restore MulOp + found! jump found_67 + loc_push + + call choice_65 + + fail! value_clear + ok! value_leaf MulOp + symbol_save MulOp + error_nonterminal MulOp + loc_pop_discard + + found_67: + ok! ast_value_push + return + + choice_65: + # / + # '*' + # '/' + + error_clear + + loc_push + error_push + + input_next "t *" + ok! test_char "*" + + error_pop_merge + ok! jump oknoast_64 + + loc_pop_rewind + loc_push + error_push + + input_next "t /" + ok! test_char "/" + + error_pop_merge + ok! jump oknoast_64 + + loc_pop_rewind + status_fail + return + + oknoast_64: + loc_pop_discard + return + # + # value Symbol 'Number' + # + + sym_Number: + # x + # ? + # (Sign) + # + + # (Digit) + + symbol_restore Number + found! jump found_80 + loc_push + ast_push + + call sequence_77 + + fail! value_clear + ok! value_reduce Number + symbol_save Number + error_nonterminal Number + ast_pop_rewind + loc_pop_discard + + found_80: + ok! ast_value_push + return + + sequence_77: + # x + # ? + # (Sign) + # + + # (Digit) + + ast_push + loc_push + error_clear + + error_push + + call optional_70 + + error_pop_merge + fail! jump failed_78 + error_push + + call poskleene_73 + + error_pop_merge + fail! jump failed_78 + + ast_pop_discard + loc_pop_discard + return + + failed_78: + ast_pop_rewind + loc_pop_rewind + return + + optional_70: + # ? + # (Sign) + + loc_push + error_push + + call sym_Sign + + error_pop_merge + fail! loc_pop_rewind + ok! loc_pop_discard + status_ok + return + + poskleene_73: + # + + # (Digit) + + loc_push + + call sym_Digit + + fail! jump failed_74 + + loop_75: + loc_pop_discard + loc_push + error_push + + call sym_Digit + + error_pop_merge + ok! jump loop_75 + status_ok + + failed_74: + loc_pop_rewind + return + # + # value Symbol 'Sign' + # + + sym_Sign: + # / + # '-' + # '+' + + symbol_restore Sign + found! jump found_86 + loc_push + + call choice_5 + + fail! value_clear + ok! value_leaf Sign + symbol_save Sign + error_nonterminal Sign + loc_pop_discard + + found_86: + ok! ast_value_push + return + # + # value Symbol 'Term' + # + + sym_Term: + # (Number) + + symbol_restore Term + found! jump found_89 + loc_push + ast_push + + call sym_Number + + fail! value_clear + ok! value_reduce Term + symbol_save Term + error_nonterminal Term + ast_pop_rewind + loc_pop_discard + + found_89: + ok! ast_value_push + return + + # + # + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section6). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section6). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PARAM](../../../../index.md#param), [PEG](../../../../index.md#peg), +[TDPL](../../../../index.md#tdpl), [context-free +languages](../../../../index.md#context_free_languages), +[conversion](../../../../index.md#conversion), +[expression](../../../../index.md#expression), [format +conversion](../../../../index.md#format_conversion), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_to_peg.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_to_peg.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_to_peg.md @@ -0,0 +1,582 @@ + +[//000000001]: # (pt::peg::to::peg - Parser Tools) +[//000000002]: # (Generated from file 'to.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::to::peg(n) 1.0.2 tcllib "Parser Tools") + +# NAME + +pt::peg::to::peg - PEG Conversion. Write PEG format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Options](#section3) + + - [PEG Specification Language](#section4) + + - [Example](#subsection1) + + - [PEG serialization format](#section5) + + - [Example](#subsection2) + + - [PE serialization format](#section6) + + - [Example](#subsection3) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::to::peg ?1.0.2? +package require pt::peg +package require pt::pe +package require text::write + +[__pt::peg::to::peg__ __reset__](#1) +[__pt::peg::to::peg__ __configure__](#2) +[__pt::peg::to::peg__ __configure__ *option*](#3) +[__pt::peg::to::peg__ __configure__ *option* *value*...](#4) +[__pt::peg::to::peg__ __convert__ *serial*](#5) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the converter from parsing expression grammars to PEG +markup. + +It resides in the Export section of the Core Layer of Parser Tools, and can be +used either directly with the other packages of this layer, or indirectly +through the export manager provided by __[pt::peg::export](pt_peg_export.md)__. +The latter is intented for use in untrusted environments and done through the +corresponding export plugin __[pt::peg::export::peg](pt_peg_export_peg.md)__ +sitting between converter and export manager. + +![](../../../../image/arch_core_eplugins.png) + +# API + +The API provided by this package satisfies the specification of the Converter +API found in the *[Parser Tools Export API](pt_to_api.md)* specification. + + - __pt::peg::to::peg__ __reset__ + + This command resets the configuration of the package to its default + settings. + + - __pt::peg::to::peg__ __configure__ + + This command returns a dictionary containing the current configuration of + the package. + + - __pt::peg::to::peg__ __configure__ *option* + + This command returns the current value of the specified configuration + *option* of the package. For the set of legal options, please read the + section [Options](#section3). + + - __pt::peg::to::peg__ __configure__ *option* *value*... + + This command sets the given configuration *option*s of the package, to the + specified *value*s. For the set of legal options, please read the section + [Options](#section3). + + - __pt::peg::to::peg__ __convert__ *serial* + + This command takes the canonical serialization of a parsing expression + grammar, as specified in section [PEG serialization format](#section5), and + contained in *serial*, and generates PEG markup encoding the grammar, per + the current package configuration. The created string is then returned as + the result of the command. + +# Options + +The converter to the PEG language recognizes the following options and changes +its behaviour as they specify. + + - __-file__ string + + The value of this option is the name of the file or other entity from which + the grammar came, for which the command is run. The default value is + __unknown__. + + - __-name__ string + + The value of this option is the name of the grammar we are processing. The + default value is __a_pe_grammar__. + + - __-user__ string + + The value of this option is the name of the user for which the command is + run. The default value is __unknown__. + + - __-template__ string + + The value of this option is a string into which to put the generated text + and the values of the other options. The various locations for user-data are + expected to be specified with the placeholders listed below. The default + value is "__@code@__". + + * __@user@__ + + To be replaced with the value of the option __-user__. + + * __@format@__ + + To be replaced with the the constant __PEG__. + + * __@file@__ + + To be replaced with the value of the option __-file__. + + * __@name@__ + + To be replaced with the value of the option __-name__. + + * __@code@__ + + To be replaced with the generated text. + +# PEG Specification Language + +__peg__, a language for the specification of parsing expression grammars is +meant to be human readable, and writable as well, yet strict enough to allow its +processing by machine. Like any computer language. It was defined to make +writing the specification of a grammar easy, something the other formats found +in the Parser Tools do not lend themselves too. + +It is formally specified by the grammar shown below, written in itself. For a +tutorial / introduction to the language please go and read the *[PEG Language +Tutorial](pt_peg_language.md)*. + + PEG pe-grammar-for-peg (Grammar) + + # -------------------------------------------------------------------- + # Syntactical constructs + + Grammar <- WHITESPACE Header Definition* Final EOF ; + + Header <- PEG Identifier StartExpr ; + Definition <- Attribute? Identifier IS Expression SEMICOLON ; + Attribute <- (VOID / LEAF) COLON ; + Expression <- Sequence (SLASH Sequence)* ; + Sequence <- Prefix+ ; + Prefix <- (AND / NOT)? Suffix ; + Suffix <- Primary (QUESTION / STAR / PLUS)? ; + Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT + / GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER + / WORDCHAR / XDIGIT + / Identifier + / OPEN Expression CLOSE + / Literal + / Class + / DOT + ; + Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE + / DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ; + Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ; + Range <- Char TO Char / Char ; + + StartExpr <- OPEN Expression CLOSE ; + void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ; + + # -------------------------------------------------------------------- + # Lexing constructs + + Identifier <- Ident WHITESPACE ; + leaf: Ident <- ([_:] / ) ([_:] / )* ; + Char <- CharSpecial / CharOctalFull / CharOctalPart + / CharUnicode / CharUnescaped + ; + + leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ; + leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ; + leaf: CharOctalPart <- "\\" [0-7][0-7]? ; + leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; + leaf: CharUnescaped <- !"\\" . ; + + void: HexDigit <- [0-9a-fA-F] ; + + void: TO <- '-' ; + void: OPENB <- "[" ; + void: CLOSEB <- "]" ; + void: APOSTROPH <- "'" ; + void: DAPOSTROPH <- '"' ; + void: PEG <- "PEG" !([_:] / ) WHITESPACE ; + void: IS <- "<-" WHITESPACE ; + leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value. + leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals. + void: SEMICOLON <- ";" WHITESPACE ; + void: COLON <- ":" WHITESPACE ; + void: SLASH <- "/" WHITESPACE ; + leaf: AND <- "&" WHITESPACE ; + leaf: NOT <- "!" WHITESPACE ; + leaf: QUESTION <- "?" WHITESPACE ; + leaf: STAR <- "*" WHITESPACE ; + leaf: PLUS <- "+" WHITESPACE ; + void: OPEN <- "(" WHITESPACE ; + void: CLOSE <- ")" WHITESPACE ; + leaf: DOT <- "." WHITESPACE ; + + leaf: ALNUM <- "" WHITESPACE ; + leaf: ALPHA <- "" WHITESPACE ; + leaf: ASCII <- "" WHITESPACE ; + leaf: CONTROL <- "" WHITESPACE ; + leaf: DDIGIT <- "" WHITESPACE ; + leaf: DIGIT <- "" WHITESPACE ; + leaf: GRAPH <- "" WHITESPACE ; + leaf: LOWER <- "" WHITESPACE ; + leaf: PRINTABLE <- "" WHITESPACE ; + leaf: PUNCT <- "" WHITESPACE ; + leaf: SPACE <- "" WHITESPACE ; + leaf: UPPER <- "" WHITESPACE ; + leaf: WORDCHAR <- "" WHITESPACE ; + leaf: XDIGIT <- "" WHITESPACE ; + + void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ; + void: COMMENT <- '#' (!EOL .)* EOL ; + void: EOL <- "\n\r" / "\n" / "\r" ; + void: EOF <- !. ; + + # -------------------------------------------------------------------- + END; + +## Example + +Our example specifies the grammar for a basic 4-operation calculator. + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +Using higher-level features of the notation, i.e. the character classes +(predefined and custom), this example can be rewritten as + + PEG calculator (Expression) + Sign <- [-+] ; + Number <- Sign? + ; + Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; + MulOp <- [*/] ; + Factor <- Term (AddOp Term)* ; + AddOp <- [-+] ; + Term <- Number ; + END; + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section6). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section6). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[conversion](../../../../index.md#conversion), +[expression](../../../../index.md#expression), [format +conversion](../../../../index.md#format_conversion), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_peg_to_tclparam.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_to_tclparam.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_peg_to_tclparam.md @@ -0,0 +1,563 @@ + +[//000000001]: # (pt::peg::to::tclparam - Parser Tools) +[//000000002]: # (Generated from file 'to.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg::to::tclparam(n) 1.0.3 tcllib "Parser Tools") + +# NAME + +pt::peg::to::tclparam - PEG Conversion. Write TCLPARAM format + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Options](#section3) + + - [Tcl/PARAM code representation of parsing expression grammars](#section4) + + - [PEG serialization format](#section5) + + - [Example](#subsection1) + + - [PE serialization format](#section6) + + - [Example](#subsection2) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg::to::tclparam ?1.0.3? + +[__pt::peg::to::tclparam__ __reset__](#1) +[__pt::peg::to::tclparam__ __configure__](#2) +[__pt::peg::to::tclparam__ __configure__ *option*](#3) +[__pt::peg::to::tclparam__ __configure__ *option* *value*...](#4) +[__pt::peg::to::tclparam__ __convert__ *serial*](#5) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package implements the converter from parsing expression grammars to +TCLPARAM markup. + +It resides in the Export section of the Core Layer of Parser Tools, and can be +used either directly with the other packages of this layer, or indirectly +through the export manager provided by __[pt::peg::export](pt_peg_export.md)__. +The latter is intented for use in untrusted environments and done through the +corresponding export plugin __pt::peg::export::tclparam__ sitting between +converter and export manager. + +![](../../../../image/arch_core_eplugins.png) + +# API + +The API provided by this package satisfies the specification of the Converter +API found in the *[Parser Tools Export API](pt_to_api.md)* specification. + + - __pt::peg::to::tclparam__ __reset__ + + This command resets the configuration of the package to its default + settings. + + - __pt::peg::to::tclparam__ __configure__ + + This command returns a dictionary containing the current configuration of + the package. + + - __pt::peg::to::tclparam__ __configure__ *option* + + This command returns the current value of the specified configuration + *option* of the package. For the set of legal options, please read the + section [Options](#section3). + + - __pt::peg::to::tclparam__ __configure__ *option* *value*... + + This command sets the given configuration *option*s of the package, to the + specified *value*s. For the set of legal options, please read the section + [Options](#section3). + + - __pt::peg::to::tclparam__ __convert__ *serial* + + This command takes the canonical serialization of a parsing expression + grammar, as specified in section [PEG serialization format](#section5), and + contained in *serial*, and generates TCLPARAM markup encoding the grammar, + per the current package configuration. The created string is then returned + as the result of the command. + +# Options + +The converter to Tcl/PARAM markup recognizes the following configuration +variables and changes its behaviour as they specify. + + - __-template__ string + + The value of this configuration variable is a string into which to put the + generated text and the other configuration settings. The various locations + for user-data are expected to be specified with the placeholders listed + below. The default value is "__@code@__". + + * __@user@__ + + To be replaced with the value of the configuration variable __-user__. + + * __@format@__ + + To be replaced with the the constant __Tcl/PARAM__. + + * __@file@__ + + To be replaced with the value of the configuration variable __-file__. + + * __@name@__ + + To be replaced with the value of the configuration variable __-name__. + + * __@code@__ + + To be replaced with the generated Tcl code. + + The following configuration variables are special, in that they will occur + within the generated code, and are replaced there as well. + + * __@runtime@__ + + To be replaced with the value of the configuration variable + __runtime-command__. + + * __@self@__ + + To be replaced with the value of the configuration variable + __self-command__. + + * __@def@__ + + To be replaced with the value of the configuration variable + __proc-command__. + + * __@ns@__ + + To be replaced with the value of the configuration variable + __namespace__. + + * __@main@__ + + To be replaced with the value of the configuration variable __main__. + + * __@prelude@__ + + To be replaced with the value of the configuration variable __prelude__. + + - __-name__ string + + The value of this configuration variable is the name of the grammar for + which the conversion is run. The default value is __a_pe_grammar__. + + - __-user__ string + + The value of this configuration variable is the name of the user for which + the conversion is run. The default value is __unknown__. + + - __-file__ string + + The value of this configuration variable is the name of the file or other + entity from which the grammar came, for which the conversion is run. The + default value is __unknown__. + + - __-runtime-command__ string + + A Tcl string representing the Tcl command or reference to it used to call + PARAM instruction from parser procedures, per the chosen framework + (template). The default value is the empty string. + + - __-self-command__ string + + A Tcl string representing the Tcl command or reference to it used to call + the parser procedures (methods ...) from another parser procedure, per the + chosen framework (template). The default value is the empty string. + + - __-proc-command__ string + + The name of the Tcl command used to define procedures (methods ...), per the + chosen framework (template). The default value is __proc__. + + - __-namespace__ string + + The name of the namespace the parser procedures (methods, ...) shall reside + in, including the trailing '::' needed to separate it from the actual + procedure name. The default value is __::__. + + - __-main__ string + + The name of the main procedure (method, ...) to be called by the chosen + framework (template) to start parsing input. The default value is + ____main__. + + - __-prelude__ string + + A snippet of code to be insert at the head of each generated parsing + command. The default value is the empty string. + + - __-indent__ integer + + The number of characters to indent each line of the generated code by. The + default value is __0__. + +While the high parameterizability of this converter, as shown by the multitude +of options it supports, is an advantage to the advanced user, allowing her to +customize the output of the converter as needed, a novice user will likely not +see the forest for the trees. + +To help these latter users two adjunct packages are provided, each containing a +canned configuration which will generate immediately useful full parsers. These +are + + - __[pt::tclparam::configuration::snit](pt_tclparam_config_snit.md)__ + + Generated parsers are classes based on the __[snit](../snit/snit.md)__ + package, i.e. snit::type's. + + - __[pt::tclparam::configuration::tcloo](pt_tclparam_config_tcloo.md)__ + + Generated parsers are classes based on the __OO__ package. + +# Tcl/PARAM code representation of parsing expression grammars + +The Tcl/PARAM representation of parsing expression grammars is Tcl code whose +execution will parse input per the grammar. The code is based on the virtual +machine documented in the *[PackRat Machine Specification](pt_param.md)*, using +its instructions and a few more to handle control flow. + +Note that the generated code by itself is not functional. It expects to be +embedded into a framework which provides services like the PARAM state, +implementations for the PARAM instructions, etc. The bulk of such a framework +has to be specified through the option __-template__. The additional options + + - __-indent__ integer + + - __-main__ string + + - __-namespace__ string + + - __-prelude__ string + + - __-proc-command__ string + + - __-runtime-command__ string + + - __-self-command__ string + +provide code snippets which help to glue framework and generated code together. +Their placeholders are in the *generated* code. + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section6). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section6). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TCLPARAM](../../../../index.md#tclparam), +[TDPL](../../../../index.md#tdpl), [context-free +languages](../../../../index.md#context_free_languages), +[conversion](../../../../index.md#conversion), +[expression](../../../../index.md#expression), [format +conversion](../../../../index.md#format_conversion), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[serialization](../../../../index.md#serialization), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_pegrammar.md Index: embedded/md/tcllib/files/modules/pt/pt_pegrammar.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_pegrammar.md @@ -0,0 +1,440 @@ + +[//000000001]: # (pt::peg - Parser Tools) +[//000000002]: # (Generated from file 'pt_pegrammar.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::peg(n) 1 tcllib "Parser Tools") + +# NAME + +pt::peg - Parsing Expression Grammar Serialization + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [PEG serialization format](#section3) + + - [Example](#subsection1) + + - [PE serialization format](#section4) + + - [Example](#subsection2) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::peg ?1? +package require pt::pe + +[__::pt::peg__ __verify__ *serial* ?*canonvar*?](#1) +[__::pt::peg__ __verify-as-canonical__ *serial*](#2) +[__::pt::peg__ __canonicalize__ *serial*](#3) +[__::pt::peg__ __print__ *serial*](#4) +[__::pt::peg__ __merge__ *seriala* *serialb*](#5) +[__::pt::peg__ __equal__ *seriala* *serialb*](#6) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides commands to work with the serializations of parsing +expression grammars as managed by the Parser Tools, and specified in section +[PEG serialization format](#section3). + +This is a supporting package in the Core Layer of Parser Tools. + +![](../../../../image/arch_core_support.png) + +# API + + - __::pt::peg__ __verify__ *serial* ?*canonvar*? + + This command verifies that the content of *serial* is a valid serialization + of a parsing expression and will throw an error if that is not the case. The + result of the command is the empty string. + + If the argument *canonvar* is specified it is interpreted as the name of a + variable in the calling context. This variable will be written to if and + only if *serial* is a valid regular serialization. Its value will be a + boolean, with __True__ indicating that the serialization is not only valid, + but also *canonical*. __False__ will be written for a valid, but + non-canonical serialization. + + For the specification of serializations see the section [PE serialization + format](#section4). + + - __::pt::peg__ __verify-as-canonical__ *serial* + + This command verifies that the content of *serial* is a valid *canonical* + serialization of a PEG and will throw an error if that is not the case. The + result of the command is the empty string. + + For the specification of canonical serializations see the section [PEG + serialization format](#section3). + + - __::pt::peg__ __canonicalize__ *serial* + + This command assumes that the content of *serial* is a valid *regular* + serialization of a PEG and will throw an error if that is not the case. + + It will then convert the input into the *canonical* serialization of the + contained PEG and return it as its result. If the input is already canonical + it will be returned unchanged. + + For the specification of regular and canonical serializations see the + section [PEG serialization format](#section3). + + - __::pt::peg__ __print__ *serial* + + This command assumes that the argument *serial* contains a valid + serialization of a parsing expression and returns a string containing that + PE in a human readable form. + + The exact format of this form is not specified and cannot be relied on for + parsing or other machine-based activities. + + For the specification of serializations see the section [PEG serialization + format](#section3). + + - __::pt::peg__ __merge__ *seriala* *serialb* + + This command accepts the regular serializations of two grammars and uses + them to create their union. The result of the command is the canonical + serialization of this unified grammar. + + A merge errors occurs if for any nonterminal symbol S occuring in both input + grammars the two input grammars specify different semantic modes. + + The semantic mode of each nonterminal symbol S is the semantic mode of S in + any of its input grammars. The previous rule made sure that for symbols + occuring in both grammars these values are identical. + + The right-hand side of each nonterminal symbol S occuring in both input + grammars is the choice between the right-hand sides of S in the input + grammars, with the parsing expression of S in *seriala* coming first, except + if both expressions are identical. In that case the first expression is + taken. + + The right-hand side of each nonterminal symbol S occuring in only one of the + input grammars is the right-hand side of S in its input grammar. + + The start expression of the unified grammar is the choice between the start + expressions of the input grammars, with the start expression of *seriala* + coming first, except if both expressions are identical. In that case the + first expression is taken + + - __::pt::peg__ __equal__ *seriala* *serialb* + + This command tests the two grammars *seriala* and *serialb* for structural + equality. The result of the command is a boolean value. It will be set to + __true__ if the expressions are identical, and __false__ otherwise. + + String equality is usable only if we can assume that the two grammars are + pure Tcl lists and dictionaries. + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section4). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section4). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_pexpr_op.md Index: embedded/md/tcllib/files/modules/pt/pt_pexpr_op.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_pexpr_op.md @@ -0,0 +1,273 @@ + +[//000000001]: # (pt::pe::op - Parser Tools) +[//000000002]: # (Generated from file 'pt_pexpr_op.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::pe::op(n) 1.0.1 tcllib "Parser Tools") + +# NAME + +pt::pe::op - Parsing Expression Utilities + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [PE serialization format](#section3) + + - [Example](#subsection1) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::pe::op ?1.0.1? +package require pt::pe ?1? +package require struct::set + +[__::pt::pe::op__ __drop__ *dropset* *pe*](#1) +[__::pt::pe::op__ __rename__ *nt* *ntnew* *pe*](#2) +[__::pt::pe::op__ __called__ *pe*](#3) +[__::pt::pe::op__ __flatten__ *pe*](#4) +[__::pt::pe::op__ __fusechars__ *pe*](#5) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides additional commands to work with the serializations of +parsing expressions as managed by the PEG and related packages, and specified in +section [PE serialization format](#section3). + +This is an internal package, for use by the higher level packages handling PEGs, +their conversion into and out of various other formats, or other uses. + +# API + + - __::pt::pe::op__ __drop__ *dropset* *pe* + + This command removes all occurences of any of the nonterminals symbols in + the set *dropset* from the parsing expression *pe*, and simplifies it. This + may result in the expression becoming "epsilon", i.e. matching nothing. + + - __::pt::pe::op__ __rename__ *nt* *ntnew* *pe* + + This command renames all occurences of the nonterminal *nt* in the parsing + expression *pe* into *ntnew*. + + - __::pt::pe::op__ __called__ *pe* + + This command extracts the set of all nonterminal symbols used, i.e. + 'called', in the parsing expression *pe*. + + - __::pt::pe::op__ __flatten__ *pe* + + This command transforms the parsing expression by eliminating sequences + nested in sequences, and choices in choices, lifting the children of the + nested expression into the parent. It further eliminates all sequences and + choices with only one child, as these are redundant. + + The resulting parsing expression is returned as the result of the command. + + - __::pt::pe::op__ __fusechars__ *pe* + + This command transforms the parsing expression by fusing adjacent terminals + in sequences and adjacent terminals and ranges in choices, it (re)constructs + highlevel *strings* and *character classes*. + + The resulting pseudo-parsing expression is returned as the result of the + command and may contain the pseudo-operators __str__ for character + sequences, aka strings, and __cl__ for character choices, aka character + classes. + + The result is called a *pseudo-parsing expression* because it is not a true + parsing expression anymore, and will fail a check with __::pt::peg verify__ + if the new pseudo-operators are present in the result, but is otherwise of + sound structure for a parsing expression. Notably, the commands __::pt::peg + bottomup__ and __::pt::peg topdown__ will process them without trouble. + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_pexpression.md Index: embedded/md/tcllib/files/modules/pt/pt_pexpression.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_pexpression.md @@ -0,0 +1,472 @@ + +[//000000001]: # (pt::pe - Parser Tools) +[//000000002]: # (Generated from file 'pt_pexpression.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::pe(n) 1.0.1 tcllib "Parser Tools") + +# NAME + +pt::pe - Parsing Expression Serialization + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [PE serialization format](#section3) + + - [Example](#subsection1) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::pe ?1.0.1? +package require char + +[__::pt::pe__ __verify__ *serial* ?*canonvar*?](#1) +[__::pt::pe__ __verify-as-canonical__ *serial*](#2) +[__::pt::pe__ __canonicalize__ *serial*](#3) +[__::pt::pe__ __print__ *serial*](#4) +[__::pt::pe__ __bottomup__ *cmdprefix* *pe*](#5) +[__cmdprefix__ *pe* *op* *arguments*](#6) +[__::pt::pe__ __topdown__ *cmdprefix* *pe*](#7) +[__::pt::pe__ __equal__ *seriala* *serialb*](#8) +[__::pt::pe__ __epsilon__](#9) +[__::pt::pe__ __dot__](#10) +[__::pt::pe__ __alnum__](#11) +[__::pt::pe__ __alpha__](#12) +[__::pt::pe__ __ascii__](#13) +[__::pt::pe__ __control__](#14) +[__::pt::pe__ __digit__](#15) +[__::pt::pe__ __graph__](#16) +[__::pt::pe__ __lower__](#17) +[__::pt::pe__ __print__](#18) +[__::pt::pe__ __punct__](#19) +[__::pt::pe__ __space__](#20) +[__::pt::pe__ __upper__](#21) +[__::pt::pe__ __wordchar__](#22) +[__::pt::pe__ __xdigit__](#23) +[__::pt::pe__ __ddigit__](#24) +[__::pt::pe__ __terminal__ *t*](#25) +[__::pt::pe__ __range__ *ta* *tb*](#26) +[__::pt::pe__ __nonterminal__ *nt*](#27) +[__::pt::pe__ __choice__ *pe*...](#28) +[__::pt::pe__ __sequence__ *pe*...](#29) +[__::pt::pe__ __repeat0__ *pe*](#30) +[__::pt::pe__ __repeat1__ *pe*](#31) +[__::pt::pe__ __optional__ *pe*](#32) +[__::pt::pe__ __ahead__ *pe*](#33) +[__::pt::pe__ __notahead__ *pe*](#34) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides commands to work with the serializations of parsing +expressions as managed by the Parser Tools, and specified in section [PE +serialization format](#section3). + +This is a supporting package in the Core Layer of Parser Tools. + +![](../../../../image/arch_core_support.png) + +# API + + - __::pt::pe__ __verify__ *serial* ?*canonvar*? + + This command verifies that the content of *serial* is a valid serialization + of a parsing expression and will throw an error if that is not the case. The + result of the command is the empty string. + + If the argument *canonvar* is specified it is interpreted as the name of a + variable in the calling context. This variable will be written to if and + only if *serial* is a valid regular serialization. Its value will be a + boolean, with __True__ indicating that the serialization is not only valid, + but also *canonical*. __False__ will be written for a valid, but + non-canonical serialization. + + For the specification of serializations see the section [PE serialization + format](#section3). + + - __::pt::pe__ __verify-as-canonical__ *serial* + + This command verifies that the content of *serial* is a valid *canonical* + serialization of a parsing expression and will throw an error if that is not + the case. The result of the command is the empty string. + + For the specification of canonical serializations see the section [PE + serialization format](#section3). + + - __::pt::pe__ __canonicalize__ *serial* + + This command assumes that the content of *serial* is a valid *regular* + serialization of a parsing expression and will throw an error if that is not + the case. + + It will then convert the input into the *canonical* serialization of this + parsing expression and return it as its result. If the input is already + canonical it will be returned unchanged. + + For the specification of regular and canonical serializations see the + section [PE serialization format](#section3). + + - __::pt::pe__ __print__ *serial* + + This command assumes that the argument *serial* contains a valid + serialization of a parsing expression and returns a string containing that + PE in a human readable form. + + The exact format of this form is not specified and cannot be relied on for + parsing or other machine-based activities. + + For the specification of serializations see the section [PE serialization + format](#section3). + + - __::pt::pe__ __bottomup__ *cmdprefix* *pe* + + This command walks the parsing expression *pe* from the bottom up to the + root, invoking the command prefix *cmdprefix* for each partial expression. + This implies that the children of a parsing expression PE are handled before + PE. + + The command prefix has the signature + + * __cmdprefix__ *pe* *op* *arguments* + + I.e. it is invoked with the parsing expression *pe* the walk is + currently at, the *op*'erator in the *pe*, and the operator's + *arguments*. + + The result returned by the command prefix replaces *pe* in the parsing + expression it was a child of, allowing transformations of the expression + tree. + + This also means that for all inner parsing expressions the contents of + *arguments* are the results of the command prefix invoked for the + children of this inner parsing expression. + + - __::pt::pe__ __topdown__ *cmdprefix* *pe* + + This command walks the parsing expression *pe* from the root down to the + leaves, invoking the command prefix *cmdprefix* for each partial expression. + This implies that the children of a parsing expression PE are handled after + PE. + + The command prefix has the same signature as for __bottomup__, see above. + + The result returned by the command prefix is *ignored*. + + - __::pt::pe__ __equal__ *seriala* *serialb* + + This command tests the two parsing expressions *seriala* and *serialb* for + structural equality. The result of the command is a boolean value. It will + be set to __true__ if the expressions are identical, and __false__ + otherwise. + + String equality is usable only if we can assume that the two parsing + expressions are pure Tcl lists. + + - __::pt::pe__ __epsilon__ + + This command constructs the atomic parsing expression for epsilon. + + - __::pt::pe__ __dot__ + + This command constructs the atomic parsing expression for dot. + + - __::pt::pe__ __alnum__ + + This command constructs the atomic parsing expression for alnum. + + - __::pt::pe__ __alpha__ + + This command constructs the atomic parsing expression for alpha. + + - __::pt::pe__ __ascii__ + + This command constructs the atomic parsing expression for ascii. + + - __::pt::pe__ __control__ + + This command constructs the atomic parsing expression for control. + + - __::pt::pe__ __digit__ + + This command constructs the atomic parsing expression for digit. + + - __::pt::pe__ __graph__ + + This command constructs the atomic parsing expression for graph. + + - __::pt::pe__ __lower__ + + This command constructs the atomic parsing expression for lower. + + - __::pt::pe__ __print__ + + This command constructs the atomic parsing expression for print. + + - __::pt::pe__ __punct__ + + This command constructs the atomic parsing expression for punct. + + - __::pt::pe__ __space__ + + This command constructs the atomic parsing expression for space. + + - __::pt::pe__ __upper__ + + This command constructs the atomic parsing expression for upper. + + - __::pt::pe__ __wordchar__ + + This command constructs the atomic parsing expression for wordchar. + + - __::pt::pe__ __xdigit__ + + This command constructs the atomic parsing expression for xdigit. + + - __::pt::pe__ __ddigit__ + + This command constructs the atomic parsing expression for ddigit. + + - __::pt::pe__ __terminal__ *t* + + This command constructs the atomic parsing expression for the terminal + symbol *t*. + + - __::pt::pe__ __range__ *ta* *tb* + + This command constructs the atomic parsing expression for the range of + terminal symbols *ta* ... *tb*. + + - __::pt::pe__ __nonterminal__ *nt* + + This command constructs the atomic parsing expression for the nonterminal + symbol *nt*. + + - __::pt::pe__ __choice__ *pe*... + + This command constructs the parsing expression representing the ordered or + prioritized choice between the argument parsing expressions. The first + argument has the highest priority. + + - __::pt::pe__ __sequence__ *pe*... + + This command constructs the parsing expression representing the sequence of + the argument parsing expression. The first argument is the first element of + the sequence. + + - __::pt::pe__ __repeat0__ *pe* + + This command constructs the parsing expression representing the zero or more + repetition of the argument parsing expression *pe*, also known as the kleene + closure. + + - __::pt::pe__ __repeat1__ *pe* + + This command constructs the parsing expression representing the one or more + repetition of the argument parsing expression *pe*, also known as the + positive kleene closure. + + - __::pt::pe__ __optional__ *pe* + + This command constructs the parsing expression representing the optionality + of the argument parsing expression *pe*. + + - __::pt::pe__ __ahead__ *pe* + + This command constructs the parsing expression representing the positive + lookahead of the argument parsing expression *pe*. + + - __::pt::pe__ __notahead__ *pe* + + This command constructs the parsing expression representing the negative + lookahead of the argument parsing expression *pe*. + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_pgen.md Index: embedded/md/tcllib/files/modules/pt/pt_pgen.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_pgen.md @@ -0,0 +1,248 @@ + +[//000000001]: # (pt::pgen - Parser Tools) +[//000000002]: # (Generated from file 'pt_pgen.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::pgen(n) 1.1 tcllib "Parser Tools") + +# NAME + +pt::pgen - Parser Generator + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Example](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::pgen ?1.1? + +[__::pt::pgen__ *inputformat* *text* *resultformat* ?*options...*?](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides a command implementing a *[parser +generator](../../../../index.md#parser_generator)* taking parsing expression +grammars as input. + +It is the implementation of method __generate__ of __[pt](../../apps/pt.md)__, +the *[Parser Tools Application](../../apps/pt.md)*. + +As such the intended audience of this document are people wishing to modify +and/or extend this part of __[pt](../../apps/pt.md)__'s functionality. Users of +__[pt](../../apps/pt.md)__ on the other hand are hereby refered to the +applications' manpage, i.e. *[Parser Tools Application](../../apps/pt.md)*. + +It resides in the User Package Layer of Parser Tools. + +![](../../../../image/arch_user_pkg.png) + +# API + + - __::pt::pgen__ *inputformat* *text* *resultformat* ?*options...*? + + This command takes the parsing expression grammar in *text* (in the format + specified by *inputformat*), and returns the same grammar in the format + *resultformat* as the result of the command. + + The two known input formats are __peg__ and __json__. Introductions to them, + including their formal specifications, can be found in the *[PEG Language + Tutorial](pt_peg_language.md)* and *[The JSON Grammar Exchange + Format](pt_json_language.md)*. The packages used to parse these formats are + + * __peg__ + + __[pt::peg::from::peg](pt_peg_from_peg.md)__ + + * __json__ + + __[pt::peg::from::json](pt_peg_from_json.md)__ + + On the output side the known formats, and the packages used to generate them + are + + * __c__ + + __[pt::peg::to::cparam](pt_peg_to_cparam.md)__ + + * __container__ + + __[pt::peg::to::container](pt_peg_to_container.md)__ + + * __critcl__ + + __[pt::peg::to::cparam](pt_peg_to_cparam.md)__ + + __[pt::cparam::configuration::critcl](pt_cparam_config_critcl.md)__ + + * __json__ + + __[pt::peg::to::json](pt_peg_to_json.md)__ + + * __oo__ + + __[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ + + __[pt::tclparam::configuration::tcloo](pt_tclparam_config_tcloo.md)__ + + * __peg__ + + __[pt::peg::to::peg](pt_peg_to_peg.md)__ + + * __snit__ + + __[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ + + __[pt::tclparam::configuration::snit](pt_tclparam_config_snit.md)__ + + The options supported by each of these formats are documented with their + respective packages. + +# Example + +In this section we are working a complete example, starting with a PEG grammar +and ending with running the parser generated from it over some input, following +the outline shown in the figure below: + +![](../../../../image/flow.png) Our grammar, assumed to the stored in the file +"calculator.peg" is + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +From this we create a snit-based parser using the script "gen" + + package require Tcl 8.5 + package require fileutil + package require pt::pgen + + lassign $argv name + set grammar [fileutil::cat $name.peg] + set pclass [pt::pgen peg $gr snit -class $name -file $name.peg -name $name] + fileutil::writeFile $name.tcl $pclass + exit 0 + +calling it like + + tclsh8.5 gen calculator + +which leaves us with the parser package and class written to the file +"calculator.tcl". Assuming that this package is then properly installed in a +place where Tcl can find it we can now use this class via a script like + + package require calculator + + lassign $argv input + set channel [open $input r] + + set parser [calculator] + set ast [$parser parse $channel] + $parser destroy + close $channel + + ... now process the returned abstract syntax tree ... + +where the abstract syntax tree stored in the variable will look like + + set ast {Expression 0 4 + {Factor 0 4 + {Term 0 2 + {Number 0 2 + {Digit 0 0} + {Digit 1 1} + {Digit 2 2} + } + } + {AddOp 3 3} + {Term 4 4 + {Number 4 4 + {Digit 4 4} + } + } + } + } + +assuming that the input file and channel contained the text + + 120+5 + +A more graphical representation of the tree would be + +![](../../../../image/expr_ast.png) Regardless, at this point it is the user's +responsibility to work with the tree to reach whatever goal she desires. I.e. +analyze it, transform it, etc. The package __[pt::ast](pt_astree.md)__ should be +of help here, providing commands to walk such ASTs structures in various ways. + +One important thing to note is that the parsers used here return a data +structure representing the structure of the input per the grammar underlying the +parser. There are *no* callbacks during the parsing process, i.e. no *parsing +actions*, as most other parsers will have. + +Going back to the last snippet of code, the execution of the parser for some +input, note how the parser instance follows the specified *[Parser +API](pt_parser_api.md)*. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_rdengine.md Index: embedded/md/tcllib/files/modules/pt/pt_rdengine.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_rdengine.md @@ -0,0 +1,940 @@ + +[//000000001]: # (pt::rde - Parser Tools) +[//000000002]: # (Generated from file 'pt_rdengine.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::rde(n) 1.1 tcllib "Parser Tools") + +# NAME + +pt::rde - Parsing Runtime Support, PARAM based + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Class API](#subsection1) + + - [Object API](#subsection2) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::rde ?1.1? +package require snit +package require struct::stack 1.5 +package require pt::ast 1.1 + +[__::pt::rde__ *objectName*](#1) +[*objectName* __destroy__](#2) +[*objectName* __reset__ *chan*](#3) +[*objectName* __complete__](#4) +[*objectName* __chan__](#5) +[*objectName* __line__](#6) +[*objectName* __column__](#7) +[*objectName* __current__](#8) +[*objectName* __location__](#9) +[*objectName* __locations__](#10) +[*objectName* __ok__](#11) +[*objectName* __value__](#12) +[*objectName* __error__](#13) +[*objectName* __errors__](#14) +[*objectName* __tokens__ ?*from* ?*to*??](#15) +[*objectName* __symbols__](#16) +[*objectName* __known__](#17) +[*objectName* __reducible__](#18) +[*objectName* __asts__](#19) +[*objectName* __ast__](#20) +[*objectName* __position__ *loc*](#21) +[*objectName* __i_input_next__ *msg*](#22) +[*objectName* __i_test_alnum__](#23) +[*objectName* __i_test_alpha__](#24) +[*objectName* __i_test_ascii__](#25) +[*objectName* __i_test_char__ *char*](#26) +[*objectName* __i_test_ddigit__](#27) +[*objectName* __i_test_digit__](#28) +[*objectName* __i_test_graph__](#29) +[*objectName* __i_test_lower__](#30) +[*objectName* __i_test_print__](#31) +[*objectName* __i_test_punct__](#32) +[*objectName* __i_test_range__ *chars* *chare*](#33) +[*objectName* __i_test_space__](#34) +[*objectName* __i_test_upper__](#35) +[*objectName* __i_test_wordchar__](#36) +[*objectName* __i_test_xdigit__](#37) +[*objectName* __i_error_clear__](#38) +[*objectName* __i_error_push__](#39) +[*objectName* __i_error_pop_merge__](#40) +[*objectName* __i_error_nonterminal__ *symbol*](#41) +[*objectName* __i_status_ok__](#42) +[*objectName* __i_status_fail__](#43) +[*objectName* __i_status_negate__](#44) +[*objectName* __i_loc_push__](#45) +[*objectName* __i_loc_pop_discard__](#46) +[*objectName* __i_loc_pop_rewind__](#47) +[*objectName* __i:ok_loc_pop_rewind__](#48) +[*objectName* __i_loc_pop_rewind/discard__](#49) +[*objectName* __i_symbol_restore__ *symbol*](#50) +[*objectName* __i_symbol_save__ *symbol*](#51) +[*objectName* __i_value_clear__](#52) +[*objectName* __i_value_clear/leaf__](#53) +[*objectName* __i_value_clear/reduce__](#54) +[*objectName* __i:ok_ast_value_push__](#55) +[*objectName* __i_ast_push__](#56) +[*objectName* __i_ast_pop_rewind__](#57) +[*objectName* __i:fail_ast_pop_rewind__](#58) +[*objectName* __i_ast_pop_rewind/discard__](#59) +[*objectName* __i_ast_pop_discard__](#60) +[*objectName* __i_ast_pop_discard/rewind__](#61) +[*objectName* __i:ok_continue__](#62) +[*objectName* __i:fail_continue__](#63) +[*objectName* __i:fail_return__](#64) +[*objectName* __i:ok_return__](#65) +[*objectName* __si:void_state_push__](#66) +[*objectName* __si:void2_state_push__](#67) +[*objectName* __si:value_state_push__](#68) +[*objectName* __si:void_state_merge__](#69) +[*objectName* __si:void_state_merge_ok__](#70) +[*objectName* __si:value_state_merge__](#71) +[*objectName* __si:value_notahead_start__](#72) +[*objectName* __si:void_notahead_exit__](#73) +[*objectName* __si:value_notahead_exit__](#74) +[*objectName* __si:kleene_abort__](#75) +[*objectName* __si:kleene_close__](#76) +[*objectName* __si:voidvoid_branch__](#77) +[*objectName* __si:voidvalue_branch__](#78) +[*objectName* __si:valuevoid_branch__](#79) +[*objectName* __si:valuevalue_branch__](#80) +[*objectName* __si:voidvoid_part__](#81) +[*objectName* __si:voidvalue_part__](#82) +[*objectName* __si:valuevalue_part__](#83) +[*objectName* __si:value_symbol_start__ *symbol*](#84) +[*objectName* __si:value_void_symbol_start__ *symbol*](#85) +[*objectName* __si:void_symbol_start__ *symbol*](#86) +[*objectName* __si:void_void_symbol_start__ *symbol*](#87) +[*objectName* __si:reduce_symbol_end__ *symbol*](#88) +[*objectName* __si:void_leaf_symbol_end__ *symbol*](#89) +[*objectName* __si:value_leaf_symbol_end__ *symbol*](#90) +[*objectName* __si:value_clear_symbol_end__ *symbol*](#91) +[*objectName* __si:void_clear_symbol_end__ *symbol*](#92) +[*objectName* __si:next_char__ *tok*](#93) +[*objectName* __si:next_range__ *toks* *toke*](#94) +[*objectName* __si:next_alnum__](#95) +[*objectName* __si:next_alpha__](#96) +[*objectName* __si:next_ascii__](#97) +[*objectName* __si:next_ddigit__](#98) +[*objectName* __si:next_digit__](#99) +[*objectName* __si:next_graph__](#100) +[*objectName* __si:next_lower__](#101) +[*objectName* __si:next_print__](#102) +[*objectName* __si:next_punct__](#103) +[*objectName* __si:next_space__](#104) +[*objectName* __si:next_upper__](#105) +[*objectName* __si:next_wordchar__](#106) +[*objectName* __si:next_xdigit__](#107) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides a class whose instances provide the runtime support for +recursive descent parsers with backtracking, as is needed for the execution of, +for example, parsing expression grammars. It implements the *[PackRat Machine +Specification](pt_param.md)*, as such that document is *required* reading to +understand both this manpage, and the package itself. The description below does +make numerous shorthand references to the PARAM's instructions and the various +parts of its architectural state. + +The package resides in the Execution section of the Core Layer of Parser Tools. + +![](../../../../image/arch_core_transform.png) + +Note: This package not only has the standard Tcl implementation, but also an +accelerator, i.e. a C implementation, based on Critcl. + +## Class API + +The package exports the API described here. + + - __::pt::rde__ *objectName* + + The command creates a new runtime object for a recursive descent parser with + backtracking and returns the fully qualified name of the object command as + its result. The API of this object command is described in the section + [Object API](#subsection2). It may be used to invoke various operations on + the object. + +## Object API + +All objects created by this package provide the following 63 methods for the +manipulation and querying of their state, which is, in essence the architectural +state of a PARAM. + +First some general methods and the state accessors. + + - *objectName* __destroy__ + + This method destroys the object, releasing all claimed memory, and deleting + the associated object command. + + - *objectName* __reset__ *chan* + + This method resets the state of the runtme to its defaults, preparing it for + the parsing of the character in the channel *chan*, which becomes IN. + + Note here that the Parser Tools are based on Tcl 8.5+. In other words, the + channel argument is not restricted to files, sockets, etc. We have the full + power of *reflected channels* available. + + It should also be noted that the parser pulls the characters from the input + stream as it needs them. If a parser created by this package has to be + operated in a push aka event-driven manner it will be necessary to go to Tcl + 8.6+ and use the __[coroutine::auto](../coroutine/coro_auto.md)__ to wrap it + into a coroutine where __[read](../../../../index.md#read)__ is properly + changed for push-operation. + + - *objectName* __complete__ + + This method completes parsing, either returning the AST made from the + elements of ARS, or throwing an error containing the current ER. + + - *objectName* __chan__ + + This method returns the handle of the channel which is IN. + + - *objectName* __line__ + + This method returns the line number for the position IN is currently at. + Note that this may not match with the line number for CL, due to + backtracking. + + - *objectName* __column__ + + This method returns the column for the position IN is currently at. Note + that this may not match with the column for CL, due to backtracking. + + - *objectName* __current__ + + This method returns CC. + + - *objectName* __location__ + + This method returns CL. + + - *objectName* __locations__ + + This method returns the LS. The topmost entry of the stack will be the first + element of the returned list. + + - *objectName* __ok__ + + This method returns ST. + + - *objectName* __value__ + + This method returns SV. + + - *objectName* __error__ + + This method returns ER. This is either the empty string for an empty ER, or + a list of 2 elements, the location the error is for, and a set of messages + which specify which symbols were expected at the location. The messages are + encoded as one of the possible atomic parsing expressions (special + operators, terminal, range, and nonterminal operator). + + - *objectName* __errors__ + + This method returns ES. The topmost entry of the stack will be the first + element of the returned list. Each entry is encoded as described for + __error__. + + - *objectName* __tokens__ ?*from* ?*to*?? + + This method returns the part of TC for the range of locations of IN starting + at *from* and ending at *to*. If *to* is not specified it is taken as + identical to *from*. If neither argument is specified the whole of TC is + returned. + + Each token in the returned list is a list of three elements itself, + containing the character at the location, and the associated line and column + numbers, in this order. + + - *objectName* __symbols__ + + This method returns a dictionary containing NC. Keys are two-element lists + containing nonterminal symbol and location, in this order. The values are + 4-tuples containing CL, ST, ER, and SV, in this order. ER is encoded as + specified for the method __error__. + + - *objectName* __known__ + + This method returns a list containing the keys of SC. They are encoded in + the same manner as is done by method __symbols__. + + - *objectName* __reducible__ + + This method returns ARS. The topmost entry of the stack will be the first + element of the returned list + + - *objectName* __asts__ + + This method returns AS. The topmost entry of the stack will be the first + element of the returned list + + - *objectName* __ast__ + + This is a convenience method returning the topmost element of ARS. + + - *objectName* __position__ *loc* + + This method returns the line and column numbers for the specified location + of IN, assuming that this location has already been reached during the + parsing process. + +The following methods implement all PARAM instructions. They all have the prefix +"i_". + +The control flow is mainly provided by Tcl's builtin commands, like __if__, +__while__, etc., plus a few guarded variants of PARAM instructions and Tcl +commands.. That means that these instruction variants will do nothing if their +guard condition is not fulfilled. They can be recognized by the prefix "i:ok_" +and "i:fail_", which denote the value ST has to have for the instruction to +execute. + +The instructions are listed in the same order they occur in the *[PackRat +Machine Specification](pt_param.md)*, with the guard variants listed after their +regular implementation, if any, or in their place. + + - *objectName* __i_input_next__ *msg* + + This method implements the PARAM instruction __input_next__. + + - *objectName* __i_test_alnum__ + + This method implements the PARAM instruction __test_alnum__. + + - *objectName* __i_test_alpha__ + + This method implements the PARAM instruction __test_alpha__. + + - *objectName* __i_test_ascii__ + + This method implements the PARAM instruction __test_ascii__. + + - *objectName* __i_test_char__ *char* + + This method implements the PARAM instruction __test_char__. + + - *objectName* __i_test_ddigit__ + + This method implements the PARAM instruction __test_ddigit__. + + - *objectName* __i_test_digit__ + + This method implements the PARAM instruction __test_digit__. + + - *objectName* __i_test_graph__ + + This method implements the PARAM instruction __test_graph__. + + - *objectName* __i_test_lower__ + + This method implements the PARAM instruction __test_lower__. + + - *objectName* __i_test_print__ + + This method implements the PARAM instruction __test_print__. + + - *objectName* __i_test_punct__ + + This method implements the PARAM instruction __test_punct__. + + - *objectName* __i_test_range__ *chars* *chare* + + This method implements the PARAM instruction __test_range__. + + - *objectName* __i_test_space__ + + This method implements the PARAM instruction __test_space__. + + - *objectName* __i_test_upper__ + + This method implements the PARAM instruction __test_upper__. + + - *objectName* __i_test_wordchar__ + + This method implements the PARAM instruction __test_wordchar__. + + - *objectName* __i_test_xdigit__ + + This method implements the PARAM instruction __test_xdigit__. + + - *objectName* __i_error_clear__ + + This method implements the PARAM instruction __error_clear__. + + - *objectName* __i_error_push__ + + This method implements the PARAM instruction __error_push__. + + - *objectName* __i_error_pop_merge__ + + This method implements the PARAM instruction __error_pop_merge__. + + - *objectName* __i_error_nonterminal__ *symbol* + + This method implements the PARAM instruction __error_nonterminal__. + + - *objectName* __i_status_ok__ + + This method implements the PARAM instruction __status_ok__. + + - *objectName* __i_status_fail__ + + This method implements the PARAM instruction __status_fail__. + + - *objectName* __i_status_negate__ + + This method implements the PARAM instruction __status_negate__. + + - *objectName* __i_loc_push__ + + This method implements the PARAM instruction __loc_push__. + + - *objectName* __i_loc_pop_discard__ + + This method implements the PARAM instruction __loc_pop_discard__. + + - *objectName* __i_loc_pop_rewind__ + + This method implements the PARAM instruction __loc_pop_rewind__. + + - *objectName* __i:ok_loc_pop_rewind__ + + This guarded method, a variant of __i_loc_pop_rewind__, executes only for + "ST == ok". + + - *objectName* __i_loc_pop_rewind/discard__ + + This method is a convenient combination of control flow and the two PARAM + instructions __loc_pop_rewind__ and __loc_pop_discard__. The former is + executed for "ST == fail", the latter for "ST == ok". + + - *objectName* __i_symbol_restore__ *symbol* + + This method implements the PARAM instruction __symbol_restore__. + + The boolean result of the check is returned as the result of the method and + can be used with standard Tcl control flow commands. + + - *objectName* __i_symbol_save__ *symbol* + + This method implements the PARAM instruction __symbol_save__. + + - *objectName* __i_value_clear__ + + This method implements the PARAM instruction __value_clear__. + + - *objectName* __i_value_clear/leaf__ + + This method is a convenient combination of control flow and the two PARAM + instructions __value_clear__ and __value_leaf__. The former is executed for + "ST == fail", the latter for "ST == ok". + + - *objectName* __i_value_clear/reduce__ + + This method is a convenient combination of control flow and the two PARAM + instructions __value_clear__ and __value_reduce__. The former is executed + for "ST == fail", the latter for "ST == ok". + + - *objectName* __i:ok_ast_value_push__ + + This method implements a guarded variant of the the PARAM instruction + __ast_value_push__, which executes only for "ST == ok". + + - *objectName* __i_ast_push__ + + This method implements the PARAM instruction __ast_push__. + + - *objectName* __i_ast_pop_rewind__ + + This method implements the PARAM instruction __ast_pop_rewind__. + + - *objectName* __i:fail_ast_pop_rewind__ + + This guarded method, a variant of __i_ast_pop_rewind__, executes only for + "ST == fail". + + - *objectName* __i_ast_pop_rewind/discard__ + + This method is a convenient combination of control flow and the two PARAM + instructions __ast_pop_rewind__ and __ast_pop_discard__. The former is + executed for "ST == fail", the latter for "ST == ok". + + - *objectName* __i_ast_pop_discard__ + + This method implements the PARAM instruction __ast_pop_discard__. + + - *objectName* __i_ast_pop_discard/rewind__ + + This method is a convenient combination of control flow and the two PARAM + instructions __ast_pop_discard__ and __ast_pop_rewind__. The former is + executed for "ST == fail", the latter for "ST == ok". + + - *objectName* __i:ok_continue__ + + This guarded method executes only for "ST == ok". Then it aborts the current + iteration of the innermost loop in the calling Tcl procedure. + + - *objectName* __i:fail_continue__ + + This guarded method executes only for "ST == fail". Then it aborts the + current iteration of the innermost loop in the calling Tcl procedure. + + - *objectName* __i:fail_return__ + + This guarded method executes only for "ST == fail". Then it aborts the + calling Tcl procedure. + + - *objectName* __i:ok_return__ + + This guarded method executes only for "ST == ok". Then it aborts the calling + Tcl procedure. + +The next set of methods are *super instructions*, meaning that each implements a +longer sequence of instructions commonly used in parsers. The combinated +instructions of the previous set, i.e. those with names matching the pattern +"i_*/*", are actually super instructions as well, albeit with limited scope, +handling 2 instructions with their control flow. The upcoming set is much +broader in scope, folding as much as six or more PARAM instructions into a +single method call. + +In this we can see the reasoning behind their use well: + + 1. By using less instructions the generated parsers become smaller, as the + common parts are now truly part of the common runtime, and not explicitly + written in the parser's code over and over again. + + 1. Using less instructions additionally reduces the overhead associated with + calls into the runtime, i.e. the cost of method dispatch and of setting up + the variable context. + + 1. Another effect of the super instructions is that their internals can be + optimized as well, especially regarding control flow, and stack use, as the + runtime internals are accessible to all instructions folded into the + sequence. + + - *objectName* __si:void_state_push__ + + This method combines + + i_loc_push + i_error_clear + i_error_push + + Parsers use it at the beginning of *void* sequences and choices with a + *void* initial branch. + + - *objectName* __si:void2_state_push__ + + This method combines + + i_loc_push + i_error_clear + i_error_push + + Parsers use it at the beginning of optional and repeated expressions. + + - *objectName* __si:value_state_push__ + + This method combines + + i_ast_push + i_loc_push + i_error_clear + i_error_push + + Parsers use it at the beginning of sequences generating an AST and choices + with an initial branch generating an AST. + + - *objectName* __si:void_state_merge__ + + This method combines + + i_error_pop_merge + i_loc_pop_rewind/discard + + Parsers use it at the end of void sequences and choices whose last branch is + void. + + - *objectName* __si:void_state_merge_ok__ + + This method combines + + i_error_pop_merge + i_loc_pop_rewind/discard + i_status_ok + + Parsers use it at the end of optional expressions + + - *objectName* __si:value_state_merge__ + + This method combines + + i_error_pop_merge + i_ast_pop_rewind/discard + i_loc_pop_rewind/discard + + Parsers use it at the end of sequences generating ASTs and choices whose + last branch generates an AST + + - *objectName* __si:value_notahead_start__ + + This method combines + + i_loc_push + i_ast_push + + Parsers use it at the beginning of negative lookahead predicates which + generate ASTs. + + - *objectName* __si:void_notahead_exit__ + + This method combines + + i_loc_pop_rewind + i_status_negate + + Parsers use it at the end of void negative lookahead predicates. + + - *objectName* __si:value_notahead_exit__ + + This method combines + + i_ast_pop_discard/rewind + i_loc_pop_rewind + i_status_negate + + Parsers use it at the end of negative lookahead predicates which generate + ASTs. + + - *objectName* __si:kleene_abort__ + + This method combines + + i_loc_pop_rewind/discard + i:fail_return + + Parsers use it to stop a positive repetition when its first, required, + expression fails. + + - *objectName* __si:kleene_close__ + + This method combines + + i_error_pop_merge + i_loc_pop_rewind/discard + i:fail_status_ok + i:fail_return + + Parsers use it at the end of repetitions. + + - *objectName* __si:voidvoid_branch__ + + This method combines + + i_error_pop_merge + i:ok_loc_pop_discard + i:ok_return + i_loc_rewind + i_error_push + + Parsers use it when transiting between branches of a choice when both are + void. + + - *objectName* __si:voidvalue_branch__ + + This method combines + + i_error_pop_merge + i:ok_loc_pop_discard + i:ok_return + i_ast_push + i_loc_rewind + i_error_push + + Parsers use it when transiting between branches of a choice when the failing + branch is void, and the next to test generates an AST. + + - *objectName* __si:valuevoid_branch__ + + This method combines + + i_error_pop_merge + i_ast_pop_rewind/discard + i:ok_loc_pop_discard + i:ok_return + i_loc_rewind + i_error_push + + Parsers use it when transiting between branches of a choice when the failing + branch generates an AST, and the next to test is void. + + - *objectName* __si:valuevalue_branch__ + + This method combines + + i_error_pop_merge + i_ast_pop_discard + i:ok_loc_pop_discard + i:ok_return + i_ast_rewind + i_loc_rewind + i_error_push + + Parsers use it when transiting between branches of a choice when both + generate ASTs. + + - *objectName* __si:voidvoid_part__ + + This method combines + + i_error_pop_merge + i:fail_loc_pop_rewind + i:fail_return + i_error_push + + Parsers use it when transiting between parts of a sequence and both are + void. + + - *objectName* __si:voidvalue_part__ + + This method combines + + i_error_pop_merge + i:fail_loc_pop_rewind + i:fail_return + i_ast_push + i_error_push + + Parsers use it when transiting between parts of a sequence and the + sucessfully matched part is void, and after it an AST is generated. + + - *objectName* __si:valuevalue_part__ + + This method combines + + i_error_pop_merge + i:fail_ast_pop_rewind + i:fail_loc_pop_rewind + i:fail_return + i_error_push + + Parsers use it when transiting between parts of a sequence and both parts + generate ASTs. + + - *objectName* __si:value_symbol_start__ *symbol* + + This method combines + + if/found? i_symbol_restore $symbol + i:found:ok_ast_value_push + i:found_return + i_loc_push + i_ast_push + + Parsers use it at the beginning of a nonterminal symbol generating an AST, + whose right-hand side may have generated an AST as well. + + - *objectName* __si:value_void_symbol_start__ *symbol* + + This method combines + + if/found? i_symbol_restore $symbol + i:found:ok_ast_value_push + i:found_return + i_loc_push + i_ast_push + + Parsers use it at the beginning of a void nonterminal symbol whose + right-hand side may generate an AST. + + - *objectName* __si:void_symbol_start__ *symbol* + + This method combines + + if/found? i_symbol_restore $symbol + i:found_return + i_loc_push + i_ast_push + + Parsers use it at the beginning of a nonterminal symbol generating an AST + whose right-hand side is void. + + - *objectName* __si:void_void_symbol_start__ *symbol* + + This method combines + + if/found? i_symbol_restore $symbol + i:found_return + i_loc_push + + Parsers use it at the beginning of a void nonterminal symbol whose + right-hand side is void as well. + + - *objectName* __si:reduce_symbol_end__ *symbol* + + This method combines + + i_value_clear/reduce $symbol + i_symbol_save $symbol + i_error_nonterminal $symbol + i_ast_pop_rewind + i_loc_pop_discard + i:ok_ast_value_push + + Parsers use it at the end of a non-terminal symbol generating an AST using + the AST generated by the right-hand side as child. + + - *objectName* __si:void_leaf_symbol_end__ *symbol* + + This method combines + + i_value_clear/leaf $symbol + i_symbol_save $symbol + i_error_nonterminal $symbol + i_loc_pop_discard + i:ok_ast_value_push + + Parsers use it at the end of a non-terminal symbol generating an AST whose + right-hand side is void. + + - *objectName* __si:value_leaf_symbol_end__ *symbol* + + This method combines + + i_value_clear/leaf $symbol + i_symbol_save $symbol + i_error_nonterminal $symbol + i_loc_pop_discard + i_ast_pop_rewind + i:ok_ast_value_push + + Parsers use it at the end of a non-terminal symbol generating an AST + discarding the AST generated by the right-hand side. + + - *objectName* __si:value_clear_symbol_end__ *symbol* + + This method combines + + i_value_clear + i_symbol_save $symbol + i_error_nonterminal $symbol + i_loc_pop_discard + i_ast_pop_rewind + + Parsers use it at the end of a void non-terminal symbol, discarding the AST + generated by the right-hand side. + + - *objectName* __si:void_clear_symbol_end__ *symbol* + + This method combines + + i_value_clear + i_symbol_save $symbol + i_error_nonterminal $symbol + i_loc_pop_discard + + Parsers use it at the end of a void non-terminal symbol with a void + right-hand side. + + - *objectName* __si:next_char__ *tok* + + - *objectName* __si:next_range__ *toks* *toke* + + - *objectName* __si:next_alnum__ + + - *objectName* __si:next_alpha__ + + - *objectName* __si:next_ascii__ + + - *objectName* __si:next_ddigit__ + + - *objectName* __si:next_digit__ + + - *objectName* __si:next_graph__ + + - *objectName* __si:next_lower__ + + - *objectName* __si:next_print__ + + - *objectName* __si:next_punct__ + + - *objectName* __si:next_space__ + + - *objectName* __si:next_upper__ + + - *objectName* __si:next_wordchar__ + + - *objectName* __si:next_xdigit__ + + These methods all combine + + i_input_next $msg + i:fail_return + + with the appropriate __i_test_xxx__ instruction. Parsers use them for + handling atomic expressions. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_tclparam_config_nx.md Index: embedded/md/tcllib/files/modules/pt/pt_tclparam_config_nx.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_tclparam_config_nx.md @@ -0,0 +1,107 @@ + +[//000000001]: # (pt::tclparam::configuration::nx - Parser Tools) +[//000000002]: # (Generated from file 'pt_tclparam_config_nx.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::tclparam::configuration::nx(n) 1.0.1 tcllib "Parser Tools") + +# NAME + +pt::tclparam::configuration::nx - Tcl/PARAM, Canned configuration, NX + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::tclparam::configuration::nx ?1.0.1? + +[__::pt::tclparam::configuration::nx__ __def__ *name* *pkg* *version* *cmdprefix*](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package is an adjunct to +__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__, to make the use of this +highly configurable package easier by providing a canned configuration. When +applied this configuration causes the package +__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ to generate __NX__-based +parser packages. + +It is a supporting package in the Core Layer of Parser Tools. + +![](../../../../image/arch_core_support.png) + +# API + + - __::pt::tclparam::configuration::nx__ __def__ *name* *pkg* *version* *cmdprefix* + + The command applies the configuration provided by this package to the + *cmdprefix*, causing the creation of __NX__-based parsers whose class is + *name*, in package *pkg* with *version*. + + The use of a command prefix as API allows application of the configuration + to not only __[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ + (__pt::peg::to::tclparam configure__), but also export manager instances and + PEG containers (__$export configuration set__ and __[$container exporter] + configuration set__ respectively). + + Or anything other command prefix accepting two arguments, option and value. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_tclparam_config_snit.md Index: embedded/md/tcllib/files/modules/pt/pt_tclparam_config_snit.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_tclparam_config_snit.md @@ -0,0 +1,107 @@ + +[//000000001]: # (pt::tclparam::configuration::snit - Parser Tools) +[//000000002]: # (Generated from file 'pt_tclparam_config_snit.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::tclparam::configuration::snit(n) 1.0.2 tcllib "Parser Tools") + +# NAME + +pt::tclparam::configuration::snit - Tcl/PARAM, Canned configuration, Snit + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::tclparam::configuration::snit ?1.0.2? + +[__::pt::tclparam::configuration::snit__ __def__ *name* *pkg* *version* *cmdprefix*](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package is an adjunct to +__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__, to make the use of this +highly configurable package easier by providing a canned configuration. When +applied this configuration causes the package +__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ to generate +__[snit](../snit/snit.md)__-based parser packages. + +It is a supporting package in the Core Layer of Parser Tools. + +![](../../../../image/arch_core_support.png) + +# API + + - __::pt::tclparam::configuration::snit__ __def__ *name* *pkg* *version* *cmdprefix* + + The command applies the configuration provided by this package to the + *cmdprefix*, causing the creation of __[snit](../snit/snit.md)__-based + parsers whose class is *name*, in package *pkg* with *version*. + + The use of a command prefix as API allows application of the configuration + to not only __[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ + (__pt::peg::to::tclparam configure__), but also export manager instances and + PEG containers (__$export configuration set__ and __[$container exporter] + configuration set__ respectively). + + Or anything other command prefix accepting two arguments, option and value. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_tclparam_config_tcloo.md Index: embedded/md/tcllib/files/modules/pt/pt_tclparam_config_tcloo.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_tclparam_config_tcloo.md @@ -0,0 +1,107 @@ + +[//000000001]: # (pt::tclparam::configuration::tcloo - Parser Tools) +[//000000002]: # (Generated from file 'pt_tclparam_config_tcloo.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::tclparam::configuration::tcloo(n) 1.0.4 tcllib "Parser Tools") + +# NAME + +pt::tclparam::configuration::tcloo - Tcl/PARAM, Canned configuration, Tcloo + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::tclparam::configuration::tcloo ?1.0.4? + +[__::pt::tclparam::configuration::tcloo__ __def__ *name* *pkg* *version* *cmdprefix*](#1) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package is an adjunct to +__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__, to make the use of this +highly configurable package easier by providing a canned configuration. When +applied this configuration causes the package +__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ to generate __OO__-based +parser packages. + +It is a supporting package in the Core Layer of Parser Tools. + +![](../../../../image/arch_core_support.png) + +# API + + - __::pt::tclparam::configuration::tcloo__ __def__ *name* *pkg* *version* *cmdprefix* + + The command applies the configuration provided by this package to the + *cmdprefix*, causing the creation of __OO__-based parsers whose class is + *name*, in package *pkg* with *version*. + + The use of a command prefix as API allows application of the configuration + to not only __[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ + (__pt::peg::to::tclparam configure__), but also export manager instances and + PEG containers (__$export configuration set__ and __[$container exporter] + configuration set__ respectively). + + Or anything other command prefix accepting two arguments, option and value. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_to_api.md Index: embedded/md/tcllib/files/modules/pt/pt_to_api.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_to_api.md @@ -0,0 +1,515 @@ + +[//000000001]: # (pt_export_api - Parser Tools) +[//000000002]: # (Generated from file 'pt_to_api.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt_export_api(i) 1 tcllib "Parser Tools") + +# NAME + +pt_export_api - Parser Tools Export API + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Converter API](#section2) + + - [Plugin API](#section3) + + - [Options](#section4) + + - [Usage](#section5) + + - [PEG serialization format](#section6) + + - [Example](#subsection1) + + - [PE serialization format](#section7) + + - [Example](#subsection2) + + - [Bugs, Ideas, Feedback](#section8) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 + +[__CONVERTER__ __reset__](#1) +[__CONVERTER__ __configure__](#2) +[__CONVERTER__ __configure__ *option*](#3) +[__CONVERTER__ __configure__ *option* *value*...](#4) +[__CONVERTER__ __convert__ *serial*](#5) +[__::export__ *serial* *configuration*](#6) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This document describes two APIs. First the API shared by all packages for the +conversion of Parsing Expression Grammars into some other format, and then the +API shared by the packages which implement the export plugins sitting on top of +the conversion packages. + +Its intended audience are people who wish to create their own converter for some +type of output, and/or an export plugin for their or some other converter. + +It resides in the Export section of the Core Layer of Parser Tools. + +![](../../../../image/arch_core_export.png) + +# Converter API + +Any (grammar) export converter has to follow the rules set out below: + + 1. A converter is a package. Its name is arbitrary, however it is recommended + to put it under the __::pt::peg::to__ namespace. + + 1. The package provides either a single Tcl command following the API outlined + below, or a class command whose instances follow the same API. The commands + which follow the API are called *converter commands*. + + 1. A converter command has to provide the following three methods with the + given signatures and semantics. Converter commands are allowed to provide + more methods of their own, but not less, and they may not provide different + semantics for the standardized methods. + + - __CONVERTER__ __reset__ + + This method has to reset the configuration of the converter to its + default settings. The result of the method has to be the empty string. + + - __CONVERTER__ __configure__ + + This method, in this form, has to return a dictionary containing the + current configuration of the converter. + + - __CONVERTER__ __configure__ *option* + + This method, in this form, has to return the current value of the + specified configuration *option* of the converter. + + Please read the section [Options](#section4) for the set of standard + options any converter has to accept. Any other options accepted by a + specific converter will be described in its manpage. + + - __CONVERTER__ __configure__ *option* *value*... + + This command, in this form, sets the specified *option*s of the + converter to the given *value*s. + + Please read the section [Options](#section4) for the set of standard + options a converter has to accept. Any other options accepted by a + specific converter will be described in its manpage. + + - __CONVERTER__ __convert__ *serial* + + This method has to accept the canonical serialization of a parsing + expression grammar, as specified in section [PEG serialization + format](#section6), and contained in *serial*. The result of the method + has to be the result of converting the input grammar into whatever the + converter is for, per its configuration. + +# Plugin API + +Any (grammar) export plugin has to follow the rules set out below: + + 1. A plugin is a package. + + 1. The name of a plugin package has the form pt::peg::export::__FOO__, where + __FOO__ is the name of the format the plugin will generate output for. + + 1. The plugin can expect that the package __pt::peg::export::plugin__ is + present, as indicator that it was invoked from a genuine plugin manager. + + It is recommended that a plugin does check for the presence of this + package. + + 1. A plugin has to provide a single command, in the global namespace, with the + signature shown below. Plugins are allowed to provide more command of their + own, but not less, and they may not provide different semantics for the + standardized command. + + - __::export__ *serial* *configuration* + + This command has to accept the canonical serialization of a parsing + expression grammar and the configuration for the converter invoked by + the plugin. The result of the command has to be the result of the + converter invoked by the plugin for th input grammar and configuration. + + * string *serial* + + This argument will contain the *canonical* serialization of the + parsing expression grammar for which to generate the output. The + specification of what a *canonical* serialization is can be found + in the section [PEG serialization format](#section6). + + * dictionary *configuration* + + This argument will contain the configuration to configure the + converter with before invoking it, as a dictionary mapping from + options to values. + + Please read the section [Options](#section4) for the set of + standard options any converter has to accept, and thus any plugin + as well. Any other options accepted by a specific plugin will be + described in its manpage. + + 1. A single usage cycle of a plugin consists of an invokation of the command + __[export](../../../../index.md#export)__. This call has to leave the + plugin in a state where another usage cycle can be run without problems. + +# Options + +Each export converter and plugin for an export converter has to accept the +options below in their __configure__ method. Converters are allowed to ignore +the contents of these options when performing a conversion, but they must not +reject them. Plugins are expected to pass the options given to them to the +converter they are invoking. + + - __-file__ string + + The value of this option is the name of the file or other entity from which + the grammar came, for which the command is run. The default value is + __unknown__. + + - __-name__ string + + The value of this option is the name of the grammar we are processing. The + default value is __a_pe_grammar__. + + - __-user__ string + + The value of this option is the name of the user for which the command is + run. The default value is __unknown__. + +# Usage + +To use a converter do + + # Get the converter (single command here, not class) + package require the-converter-package + + # Provide a configuration + theconverter configure ... + + # Perform the conversion + set result [theconverter convert $thegrammarserial] + + ... process the result ... + +To use a plugin __FOO__ do + + # Get an export plugin manager + package require pt::peg::export + pt::peg::export E + + # Provide a configuration + E configuration set ... + + # Run the plugin, and the converter inside. + set result [E export serial $grammarserial FOO] + + ... process the result ... + +# PEG serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expression Grammars as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a PEG may +have more than one regular serialization only exactly one of them will be +*canonical*. + + - regular serialization + + The serialization of any PEG is a nested Tcl dictionary. + + This dictionary holds a single key, __pt::grammar::peg__, and its value. + This value holds the contents of the grammar. + + The contents of the grammar are a Tcl dictionary holding the set of + nonterminal symbols and the starting expression. The relevant keys and their + values are + + * __rules__ + + The value is a Tcl dictionary whose keys are the names of the + nonterminal symbols known to the grammar. + + Each nonterminal symbol may occur only once. + + The empty string is not a legal nonterminal symbol. + + The value for each symbol is a Tcl dictionary itself. The relevant + keys and their values in this dictionary are + + + __is__ + + The value is the serialization of the parsing expression + describing the symbols sentennial structure, as specified + in the section [PE serialization format](#section7). + + + __mode__ + + The value can be one of three values specifying how a + parser should handle the semantic value produced by the + symbol. + + - __value__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal itself, which has the ASTs of the + symbol's right hand side as its children. + + - __leaf__ + + The semantic value of the nonterminal symbol is an + abstract syntax tree consisting of a single node node + for the nonterminal, without any children. Any ASTs + generated by the symbol's right hand side are + discarded. + + - __void__ + + The nonterminal has no semantic value. Any ASTs + generated by the symbol's right hand side are + discarded (as well). + + * __start__ + + The value is the serialization of the start parsing expression of + the grammar, as specified in the section [PE serialization + format](#section7). + + The terminal symbols of the grammar are specified implicitly as the set of + all terminal symbols used in the start expression and on the RHS of the + grammar rules. + + - canonical serialization + + The canonical serialization of a grammar has the format as specified in the + previous item, and then additionally satisfies the constraints below, which + make it unique among all the possible serializations of this grammar. + + The keys found in all the nested Tcl dictionaries are sorted in ascending + dictionary order, as generated by Tcl's builtin command __lsort -increasing + -dict__. + + The string representation of the value is the canonical representation of a + Tcl dictionary. I.e. it does not contain superfluous whitespace. + +## Example + +Assuming the following PEG for simple mathematical expressions + + PEG calculator (Expression) + Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; + Sign <- '-' / '+' ; + Number <- Sign? Digit+ ; + Expression <- Term (AddOp Term)* ; + MulOp <- '*' / '/' ; + Term <- Factor (MulOp Factor)* ; + AddOp <- '+'/'-' ; + Factor <- '(' Expression ')' / Number ; + END; + +then its canonical serialization (except for whitespace) is + + pt::grammar::peg { + rules { + AddOp {is {/ {t -} {t +}} mode value} + Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} + Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} + Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} + MulOp {is {/ {t *} {t /}} mode value} + Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} + Sign {is {/ {t -} {t +}} mode value} + Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} + } + start {n Expression} + } + +# PE serialization format + +Here we specify the format used by the Parser Tools to serialize Parsing +Expressions as immutable values for transport, comparison, etc. + +We distinguish between *regular* and *canonical* serializations. While a parsing +expression may have more than one regular serialization only exactly one of them +will be *canonical*. + + - Regular serialization + + * __Atomic Parsing Expressions__ + + The string __epsilon__ is an atomic parsing expression. It matches the + empty string. + + The string __dot__ is an atomic parsing expression. It matches any + character. + + The string __alnum__ is an atomic parsing expression. It matches any + Unicode alphabet or digit character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __alpha__ is an atomic parsing expression. It matches any + Unicode alphabet character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ascii__ is an atomic parsing expression. It matches any + Unicode character below U0080. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __control__ is an atomic parsing expression. It matches any + Unicode control character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __digit__ is an atomic parsing expression. It matches any + Unicode digit character. Note that this includes characters outside of + the [0..9] range. This is a custom extension of PEs based on Tcl's + builtin command __string is__. + + The string __graph__ is an atomic parsing expression. It matches any + Unicode printing character, except for space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __lower__ is an atomic parsing expression. It matches any + Unicode lower-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __print__ is an atomic parsing expression. It matches any + Unicode printing character, including space. This is a custom extension + of PEs based on Tcl's builtin command __string is__. + + The string __punct__ is an atomic parsing expression. It matches any + Unicode punctuation character. This is a custom extension of PEs based + on Tcl's builtin command __string is__. + + The string __space__ is an atomic parsing expression. It matches any + Unicode space character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __upper__ is an atomic parsing expression. It matches any + Unicode upper-case alphabet character. This is a custom extension of PEs + based on Tcl's builtin command __string is__. + + The string __wordchar__ is an atomic parsing expression. It matches any + Unicode word character. This is any alphanumeric character (see alnum), + and any connector punctuation characters (e.g. underscore). This is a + custom extension of PEs based on Tcl's builtin command __string is__. + + The string __xdigit__ is an atomic parsing expression. It matches any + hexadecimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __string is__. + + The string __ddigit__ is an atomic parsing expression. It matches any + decimal digit character. This is a custom extension of PEs based on + Tcl's builtin command __regexp__. + + The expression [list t __x__] is an atomic parsing expression. It + matches the terminal string __x__. + + The expression [list n __A__] is an atomic parsing expression. It + matches the nonterminal __A__. + + * __Combined Parsing Expressions__ + + For parsing expressions __e1__, __e2__, ... the result of [list / __e1__ + __e2__ ... ] is a parsing expression as well. This is the *ordered + choice*, aka *prioritized choice*. + + For parsing expressions __e1__, __e2__, ... the result of [list x __e1__ + __e2__ ... ] is a parsing expression as well. This is the *sequence*. + + For a parsing expression __e__ the result of [list * __e__] is a parsing + expression as well. This is the *kleene closure*, describing zero or + more repetitions. + + For a parsing expression __e__ the result of [list + __e__] is a parsing + expression as well. This is the *positive kleene closure*, describing + one or more repetitions. + + For a parsing expression __e__ the result of [list & __e__] is a parsing + expression as well. This is the *and lookahead predicate*. + + For a parsing expression __e__ the result of [list ! __e__] is a parsing + expression as well. This is the *not lookahead predicate*. + + For a parsing expression __e__ the result of [list ? __e__] is a parsing + expression as well. This is the *optional input*. + + - Canonical serialization + + The canonical serialization of a parsing expression has the format as + specified in the previous item, and then additionally satisfies the + constraints below, which make it unique among all the possible + serializations of this parsing expression. + + The string representation of the value is the canonical representation of a + pure Tcl list. I.e. it does not contain superfluous whitespace. + + Terminals are *not* encoded as ranges (where start and end of the range are + identical). + +## Example + +Assuming the parsing expression shown on the right-hand side of the rule + + Expression <- Term (AddOp Term)* + +then its canonical serialization (except for whitespace) is + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/pt/pt_util.md Index: embedded/md/tcllib/files/modules/pt/pt_util.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/pt/pt_util.md @@ -0,0 +1,113 @@ + +[//000000001]: # (pt::util - Parser Tools) +[//000000002]: # (Generated from file 'pt_util.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (pt::util(n) 1.1 tcllib "Parser Tools") + +# NAME + +pt::util - General utilities + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require pt::ast ?1.1? + +[__::pt::util__ __error2readable__ *error* *text*](#1) +[__::pt::util__ __error2position__ *error* *text*](#2) +[__::pt::util__ __error2text__ *error*](#3) + +# DESCRIPTION + +Are you lost ? Do you have trouble understanding this document ? In that case +please read the overview provided by the *[Introduction to Parser +Tools](pt_introduction.md)*. This document is the entrypoint to the whole system +the current package is a part of. + +This package provides general utility commands. + +This is a supporting package in the Core Layer of Parser Tools. + +![](../../../../image/arch_core_support.png) + +# API + + - __::pt::util__ __error2readable__ *error* *text* + + This command takes the structured form of a syntax *error* as thrown by + parser runtimes and the input *text* to the parser which caused that error + and returns a string describing the error in a human-readable form. + + The input *text* is required to convert the character position of the error + into a more readable line/column format, and to provide excerpts of the + input around the error position. + + - __::pt::util__ __error2position__ *error* *text* + + This command takes the structured form of a syntax *error* as thrown by + parser runtimes and the input *text* to the parser which caused that error + and returns a 2-element list containing the line number and column index for + the error's character position in the input, in this order. + + - __::pt::util__ __error2text__ *error* + + This command takes the structured form of a syntax *error* as thrown by + parser runtimes and returns a list of strings, each describing a possible + expected input in a human-readable form. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *pt* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_), +[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl), +[context-free languages](../../../../index.md#context_free_languages), +[expression](../../../../index.md#expression), +[grammar](../../../../index.md#grammar), +[matching](../../../../index.md#matching), +[parser](../../../../index.md#parser), [parsing +expression](../../../../index.md#parsing_expression), [parsing expression +grammar](../../../../index.md#parsing_expression_grammar), [push down +automaton](../../../../index.md#push_down_automaton), [recursive +descent](../../../../index.md#recursive_descent), +[state](../../../../index.md#state), [top-down parsing +languages](../../../../index.md#top_down_parsing_languages), +[transducer](../../../../index.md#transducer) + +# CATEGORY + +Parsing and Grammars + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/rc4/rc4.md Index: embedded/md/tcllib/files/modules/rc4/rc4.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/rc4/rc4.md @@ -0,0 +1,150 @@ + +[//000000001]: # (rc4 - RC4 Stream Cipher) +[//000000002]: # (Generated from file 'rc4.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (rc4(n) 1.1.0 tcllib "RC4 Stream Cipher") + +# NAME + +rc4 - Implementation of the RC4 stream cipher + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [PROGRAMMING INTERFACE](#section3) + + - [EXAMPLES](#section4) + + - [AUTHORS](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require rc4 ?1.1.0? + +[__::rc4::rc4__ ?*-hex*? *-key keyvalue* ?*-command lst*? ?*-out channel*? [ *-in channel* | *-infile filename* | *string* ]](#1) +[__::rc4::RC4Init__ *keydata*](#2) +[__::rc4::RC4__ *Key* *data*](#3) +[__::rc4::RC4Final__ *Key*](#4) + +# DESCRIPTION + +This package is an implementation in Tcl of the RC4 stream cipher developed by +Ron Rivest of RSA Data Security Inc. The cipher was a trade secret of RSA but +was reverse-engineered and published to the internet in 1994. It is used in a +number of network protocols for securing communications. To evade trademark +restrictions this cipher is sometimes known as ARCFOUR. + +# COMMANDS + + - __::rc4::rc4__ ?*-hex*? *-key keyvalue* ?*-command lst*? ?*-out channel*? [ *-in channel* | *-infile filename* | *string* ] + + Perform the RC4 algorithm on either the data provided by the argument or on + the data read from the *-in* channel. If an *-out* channel is given then the + result will be written to this channel. Giving the *-hex* option will return + a hexadecimal encoded version of the result if not using an *-out* channel. + + The data to be processes can be specified either as a string argument to the + rc4 command, or as a filename or a pre-opened channel. If the *-infile* + argument is given then the file is opened, the data read and processed and + the file is closed. If the *-in* argument is given then data is read from + the channel until the end of file. The channel is not closed. If the *-out* + argument is given then the processing result is written to this channel. + + If *-command* is provided then the rc4 command does not return anything. + Instead the command provided is called with the rc4 result data appended as + the final parameter. This is most useful when reading from Tcl channels as a + fileevent is setup on the channel and the data processed in chunks + + Only one of *-infile*, *-in* or *string* should be given. + +# PROGRAMMING INTERFACE + + - __::rc4::RC4Init__ *keydata* + + Initialize a new RC4 key. The *keydata* is any amount of binary data and is + used to initialize the cipher internal state. + + - __::rc4::RC4__ *Key* *data* + + Encrypt or decrypt the input data using the key obtained by calling + __RC4Init__. + + - __::rc4::RC4Final__ *Key* + + This should be called to clean up resources associated with *Key*. Once this + function has been called the key is destroyed. + +# EXAMPLES + + % set keydata [binary format H* 0123456789abcdef] + % rc4::rc4 -hex -key $keydata HelloWorld + 3cf1ae8b7f1c670b612f + % rc4::rc4 -hex -key $keydata [binary format H* 3cf1ae8b7f1c670b612f] + HelloWorld + + set Key [rc4::RC4Init "key data"] + append ciphertext [rc4::RC4 $Key $plaintext] + append ciphertext [rc4::RC4 $Key $additional_plaintext] + rc4::RC4Final $Key + + proc ::Finish {myState data} { + DoStuffWith $myState $data + } + rc4::rc4 -in $socket -command [list ::Finish $ApplicationState] + +# AUTHORS + +Pat Thoyts + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *rc4* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[aes(n)](../aes/aes.md), [blowfish(n)](../blowfish/blowfish.md), +[des(n)](../des/des.md) + +# KEYWORDS + +[arcfour](../../../../index.md#arcfour), [data +integrity](../../../../index.md#data_integrity), +[encryption](../../../../index.md#encryption), [rc4](../../../../index.md#rc4), +[security](../../../../index.md#security), [stream +cipher](../../../../index.md#stream_cipher) + +# CATEGORY + +Hashes, checksums, and encryption + +# COPYRIGHT + +Copyright © 2003, Pat Thoyts ADDED embedded/md/tcllib/files/modules/rcs/rcs.md Index: embedded/md/tcllib/files/modules/rcs/rcs.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/rcs/rcs.md @@ -0,0 +1,307 @@ + +[//000000001]: # (rcs - RCS low level utilities) +[//000000002]: # (Generated from file 'rcs.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (rcs(n) 2.0.2 tcllib "RCS low level utilities") + +# NAME + +rcs - RCS low level utilities + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [TEXT DICT DATA STRUCTURE](#section3) + + - [RCS PATCH FORMAT](#section4) + + - [RCS PATCH COMMAND LIST](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require rcs ?0.1? + +[__::rcs::text2dict__ *text*](#1) +[__::rcs::dict2text__ *dict*](#2) +[__::rcs::file2dict__ *filename*](#3) +[__::rcs::dict2file__ *filename* *dict*](#4) +[__::rcs::decodeRcsPatch__ *text*](#5) +[__::rcs::encodeRcsPatch__ *pcmds*](#6) +[__::rcs::applyRcsPatch__ *text* *pcmds*](#7) + +# DESCRIPTION + +The *Revision Control System*, short *[RCS](../../../../index.md#rcs)*, is a set +of applications and related data formats which allow a system to persist the +history of changes to a text. It, and its relative SCCS are the basis for many +other such systems, like *[CVS](../../../../index.md#cvs)*, etc. + +This package *does not* implement RCS. + +It only provides a number of low level commands which should be useful in the +implementation of any revision management system, namely: + + 1. The conversion of texts into and out of a data structures which allow the + easy modification of such text by *patches*, i.e. sequences of instructions + for the transformation of one text into an other. + + 1. And the conversion of one particular format for patches, the so-called *RCS + patches*, into and out of data structures which allow their easy + application to texts. + +# COMMANDS + + - __::rcs::text2dict__ *text* + + Converts the argument *text* into a dictionary containing and representing + the same text in an indexed form and returns that dictionary as its result. + More information about the format of the result can be found in section + [TEXT DICT DATA STRUCTURE](#section3). This command returns the *canonical* + representation of the input. + + - __::rcs::dict2text__ *dict* + + This command provides the complementary operation to __::rcs::text2dict__. + It converts a dictionary in the form described in section [TEXT DICT DATA + STRUCTURE](#section3) back into a text and returns that text as its result. + The command does accept non-canonical representations of the text as its + input. + + - __::rcs::file2dict__ *filename* + + This command is identical to __::rcs::text2dict__, except that it reads the + text to convert from the file with path *filename*. The file has to exist + and must be readable as well. + + - __::rcs::dict2file__ *filename* *dict* + + This command is identical to __::rcs::2dict2text__, except that it stores + the resulting text in the file with path *filename*. The file is created if + it did not exist, and must be writable. The result of the command is the + empty string. + + - __::rcs::decodeRcsPatch__ *text* + + Converts the *text* argument into a patch command list (PCL) as specified in + the section [RCS PATCH COMMAND LIST](#section5) and returns this list as its + result. It is assumed that the input text is in *[diff -n + format](../../../../index.md#diff_n_format)*, also known as *[RCS + patch](../../../../index.md#rcs_patch)* format, as specified in the section + [RCS PATCH FORMAT](#section4). Please note that the command ignores no-ops + in the input, in other words the resulting PCL contains only instructions + doing something. + + - __::rcs::encodeRcsPatch__ *pcmds* + + This command provides the complementary operation to + __::rcs::decodeRcsPatch__. It convert a patch comand list (PCL) list as + specified in the section [RCS PATCH COMMAND LIST](#section5) back into a + text in [RCS PATCH FORMAT](#section4) and returns that text as its result. + + Note that this command and __::rcs::decodeRcsPatch__ are not exactly + complementary, as the latter strips no-ops from its input, which the encoder + cannot put back anymore into the generated RCS patch. In other words, the + result of a decode/encode step may not match the original input at the + character level, but it will match it at the functional level. + + - __::rcs::applyRcsPatch__ *text* *pcmds* + + This operation applies a patch in the form of a PCL to a text given in the + form of a dictionary and returns the modified text, again as dictionary, as + its result. + + To handle actual text use the commands __::rcs::text2dict__ (or equivalent) + and __::rcs::decodeRcsPatch__ to transform the inputs into data structures + acceptable to this command. Analogously use the command __::rcs::dict2text__ + (or equivalent) to transform the result of this command into actuall text as + required. + +# TEXT DICT DATA STRUCTURE + +A text dictionary is a dictionary whose keys are integer numbers and text +strings as the associated values. The keys represent the line numbers of a text +and the values the text of that line. Note that one text can have many +representations as a dictionary, as the index values only have to be properly +ordered for reconstruction, their exact values do not matter. Similarly the +strings may actually span multiple physical lines. + +The text + + Hello World, + how are you ? + Fine, and you ? + +for example can be represented by + + {{1 {Hello World,}} {2 {how are you ?}} {3 {Fine, and you ?}}} + +or + + {{5 {Hello World,}} {8 {how are you ?}} {9 {Fine, and you ?}}} + +or + + {{-1 {Hello World, + how are you ?}} {4 {Fine, and you ?}}} + +The first dictionary is the *canonical* representation of the text, with line +numbers starting at __1__, increasing in steps of __1__ and without gaps, and +each value representing exactly one physical line. + +All the commands creating dictionaries from text will return the canonical +representation of their input text. The commands taking a dictionary and +returning text will generally accept all representations, canonical or not. + +The result of applying a patch to a text dictionary will in general cause the +dictionary to become non-canonical. + +# RCS PATCH FORMAT + +A *[patch](../../../../index.md#patch)* is in general a series of instructions +how to transform an input text T into a different text T', and also encoded in +text form as well. + +The text format for patches understood by this package is a very simple one, +known under the names *[RCS patch](../../../../index.md#rcs_patch)* or *[diff -n +format](../../../../index.md#diff_n_format)*. + +Patches in this format contain only two different commands, for the deletion of +old text, and addition of new text. The replacement of some text by a different +text is handled as combination of a deletion following by an addition. + +The format is line oriented, with each line containing either a command or text +data associated with the preceding command. The first line of a *[RCS +patch](../../../../index.md#rcs_patch)* is always a command line. + +The commands are: + + - "" + + The empty line is a command which does nothing. + + - "a__start__ __n__" + + A line starting with the character __a__ is a command for the addition of + text to the output. It is followed by __n__ lines of text data. When + applying the patch the data is added just between the lines __start__ and + __start__+1. The same effect is had by appending the data to the existing + text on line __start__. A non-existing line __start__ is created. + + - "d__start__ __n__" + + A line starting with the character __d__ is a command for the deletion of + text from the output. When applied it deletes __n__ lines of text, and the + first line deleted is at index __start__. + +Note that the line indices __start__ always refer to the text which is +transformed as it is in its original state, without taking the precending +changes into account. + +Note also that the instruction have to be applied in the order they occur in the +patch, or in a manner which produces the same result as in-order application. + +This is the format of results returned by the command __::rcs::decodeRcsPatch__ +and accepted by the commands __::rcs::encodeRcsPatch__ and +__::rcs::appplyRcsPatch__ resp. Note however that the decoder will strip no-op +commands, and the encoder will not generate no-ops, making them not fully +complementary at the textual level, only at the functional level. + +And example of a RCS patch is + + d1 2 + d4 1 + a4 2 + The named is the mother of all things. + + a11 3 + They both may be called deep and profound. + Deeper and more profound, + The door of all subtleties! + +# RCS PATCH COMMAND LIST + +Patch command lists (sort: PCL's) are the data structures generated by patch +decoder command and accepted by the patch encoder and applicator commands. They +represent RCS patches in the form of Tcl data structures. + +A PCL is a list where each element represents a single patch instruction, either +an addition, or a deletion. The elements are lists themselves, where the first +item specifies the command and the remainder represent the arguments of the +command. + + - a + + This is the instruction for the addition of text. It has two arguments, the + index of the line where to add the text, and the text to add, in this order. + + - d + + This is the instruction for the deletion of text. It has two arguments, the + index of the line where to start deleting text, and the number of lines to + delete, in this order. + +This is the format returned by the patch decoder command and accepted as input +by the patch encoder and applicator commands. + +An example for a patch command is shown below, it represents the example RCS +patch found in section [RCS PATCH FORMAT](#section4). + + {{d 1 2} {d 4 1} {a 4 {The named is the mother of all things. + + }} {a 11 {They both may be called deep and profound. + Deeper and more profound, + The door of all subtleties!}}} + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *rcs* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[struct](../../../../index.md#struct), [textutil](../textutil/textutil.md) + +# KEYWORDS + +[CVS](../../../../index.md#cvs), [RCS](../../../../index.md#rcs), [RCS +patch](../../../../index.md#rcs_patch), [SCCS](../../../../index.md#sccs), [diff +-n format](../../../../index.md#diff_n_format), +[patching](../../../../index.md#patching), [text +conversion](../../../../index.md#text_conversion), [text +differences](../../../../index.md#text_differences) + +# CATEGORY + +Text processing + +# COPYRIGHT + +Copyright © 2005, Andreas Kupries +Copyright © 2005, Colin McCormack ADDED embedded/md/tcllib/files/modules/report/report.md Index: embedded/md/tcllib/files/modules/report/report.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/report/report.md @@ -0,0 +1,447 @@ + +[//000000001]: # (report - Matrix reports) +[//000000002]: # (Generated from file 'report.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (report(n) 0.3.2 tcllib "Matrix reports") + +# NAME + +report - Create and manipulate report objects + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [REGIONS](#section2) + + - [LINES](#section3) + + - [TEMPLATES](#section4) + + - [STYLES](#section5) + + - [REPORT METHODS](#section6) + + - [EXAMPLES](#section7) + + - [Bugs, Ideas, Feedback](#section8) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require report ?0.3.2? + +[__::report::report__ *reportName* *columns* ?__style__ *style arg...*?](#1) +[__reportName__ *option* ?*arg arg ...*?](#2) +[__::report::defstyle__ *styleName arguments script*](#3) +[__::report::rmstyle__ *styleName*](#4) +[__::report::stylearguments__ *styleName*](#5) +[__::report::stylebody__ *styleName*](#6) +[__::report::styles__](#7) +[*reportName* __destroy__](#8) +[*reportName* *templatecode* __disable__|__enable__](#9) +[*reportName* *templatecode* __enabled__](#10) +[*reportName* *templatecode* __get__](#11) +[*reportName* *templatecode* __set__ *templatedata*](#12) +[*reportName* __tcaption__ ?*size*?](#13) +[*reportName* __bcaption__ *size*](#14) +[*reportName* __size__ *column* ?*number*|__dyn__?](#15) +[*reportName* __sizes__ ?*size-list*?](#16) +[*reportName* __pad__ *column* ?__left__|__right__|__both__ ?*padstring*??](#17) +[*reportName* __justify__ *column* ?__left__|__right__|__center__?](#18) +[*reportName* __printmatrix__ *matrix*](#19) +[*reportName* __printmatrix2channel__ *matrix chan*](#20) +[*reportName* __[columns](../../../../index.md#columns)__](#21) + +# DESCRIPTION + +This package provides report objects which can be used by the formatting methods +of matrix objects to generate tabular reports of the matrix in various forms. +The report objects defined here break each report down into three +[REGIONS](#section2) and ten classes of *[lines](../../../../index.md#lines)* +(various separator- and data-lines). See the following section for more detailed +explanations. + + - __::report::report__ *reportName* *columns* ?__style__ *style arg...*? + + Creates a new report object for a report having *columns* columns with an + associated global Tcl command whose name is *reportName*. This command may + be used to invoke various configuration operations on the report. It has the + following general form: + + * __reportName__ *option* ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. See + section [REPORT METHODS](#section6) for more explanations. If no + __style__ is specified the report will use the builtin style __plain__ + as its default configuration. + + - __::report::defstyle__ *styleName arguments script* + + Defines the new style *styleName*. See section [STYLES](#section5) for more + information. + + - __::report::rmstyle__ *styleName* + + Deletes the style *styleName*. Trying to delete an unknown or builtin style + will result in an error. Beware, this command will not check that there are + no other styles depending on the deleted one. Deleting a style which is + still used by another style FOO will result in a runtime error when FOO is + applied to a newly instantiated report. + + - __::report::stylearguments__ *styleName* + + This introspection command returns the list of arguments associated with the + style *styleName*. + + - __::report::stylebody__ *styleName* + + This introspection command returns the script associated with the style + *styleName*. + + - __::report::styles__ + + This introspection command returns a list containing the names of all styles + known to the package at the time of the call. The order of the names in the + list reflects the order in which the styles were created. In other words, + the first item is the predefined style __plain__, followed by the first + style defined by the user, and so on. + +# REGIONS + +The three regions are the *top caption*, *data area* and *bottom caption*. These +are, roughly speaking, the title, the values to report and a title at the +bottom. The size of the caption regions can be specified by the user as the +number of rows they occupy in the matrix to format. The size of the data area is +specified implicitly. + +# LINES + +[TEMPLATES](#section4) are associated with each of the ten line classes, +defining the formatting for this kind of line. The user is able to enable and +disable the separator lines at will, but not the data lines. Their usage is +solely determined by the number of rows contained in the three regions. Data +lines and all enabled separators must have a template associated with them. + +Note that the data-lines in a report and the rows in the matrix the report was +generated from are *not* in a 1:1 relationship if any row in the matrix has a +height greater than one. + +The different kinds of lines and the codes used by the report methods to address +them are: + + - __top__ + + The topmost line of a report. Separates the report from anything which came + before it. The user can enable the usage of this line at will. + + - __topdatasep__ + + This line is used to separate the data rows in the top caption region, if it + contains more than one row and the user enabled its usage. + + - __topcapsep__ + + This line is used to separate the top caption and data regions, if the top + caption is not empty and the user enabled its usage. + + - __datasep__ + + This line is used to separate the data rows in the data region, if it + contains more than one row and the user enabled its usage. + + - __botcapsep__ + + This line is used to separate the data and bottom caption regions, if the + bottom caption is not empty and the user enabled its usage. + + - __botdatasep__ + + This line is used to separate the data rows in the bottom caption region, if + it contains more than one row and the user enabled its usage. + + - __bottom__ + + The bottommost line of a report. Separates the report from anything which + comes after it. The user can enable the usage of this line at will. + + - __topdata__ + + This line defines the format of data lines in the top caption region of the + report. + + - __data__ + + This line defines the format of data lines in the data region of the report. + + - __botdata__ + + This line defines the format of data lines in the bottom caption region of + the report. + +# TEMPLATES + +Each template is a list of strings used to format the line it is associated +with. For a report containing __n__ columns a template for a data line has to +contain "__n__+1" items and a template for a separator line "2*__n__+1" items. + +The items in a data template specify the strings used to separate the column +information. Together with the corresponding items in the separator templates +they form the vertical lines in the report. + +*Note* that the corresponding items in all defined templates have to be of equal +length. This will be checked by the report object. The first item defines the +leftmost vertical line and the last item defines the rightmost vertical line. +The item at index __k__ ("1",...,"__n__-2") separates the information in the +columns "__k__-1" and "__k__". + +The items in a separator template having an even-numbered index ("0","2",...) +specify the column separators. The item at index "2*__k__" +("0","2",...,"2*__n__") corresponds to the items at index "__k__" in the data +templates. + +The items in a separator template having an odd-numbered index ("1","3",...) +specify the strings used to form the horizontal lines in the separator lines. +The item at index "2*__k__+1" ("1","3",...,"2*__n__+1") corresponds to column +"__k__". When generating the horizontal lines the items are replicated to be at +least as long as the size of their column and then cut to the exact size. + +# STYLES + +Styles are a way for the user of this package to define common configurations +for report objects and then use them later during the actual instantiation of +report objects. They are defined as tcl scripts which when executed configure +the report object into the requested configuration. + +The command to define styles is __::report::defstyle__. Its last argument is the +tcl __script__ performing the actual reconfiguration of the report object to +obtain the requested style. + +In this script the names of all previously defined styles are available as +commands, as are all commands found in a safe interpreter and the configuration +methods of report objects. The latter implicitly operate on the object currently +executing the style script. The __arguments__ declared here are available in the +__script__ as variables. When calling the command of a previously declared style +all the arguments expected by it have to be defined in the call. + +# REPORT METHODS + +The following commands are possible for report objects: + + - *reportName* __destroy__ + + Destroys the report, including its storage space and associated command. + + - *reportName* *templatecode* __disable__|__enable__ + + Enables or disables the usage of the template addressed by the + *templatecode*. Only the codes for separator lines are allowed here. It is + not possible to enable or disable data lines. + + Enabling a template causes the report to check all used templates for + inconsistencies in the definition of the vertical lines (See section + [TEMPLATES](#section4)). + + - *reportName* *templatecode* __enabled__ + + Returns the whether the template addressed by the *templatecode* is + currently enabled or not. + + - *reportName* *templatecode* __get__ + + Returns the template currently associated with the kind of line addressed by + the *templatecode*. All known templatecodes are allowed here. + + - *reportName* *templatecode* __set__ *templatedata* + + Sets the template associated with the kind of line addressed by the + *templatecode* to the new value in *templatedata*. See section + [TEMPLATES](#section4) for constraints on the length of templates. + + - *reportName* __tcaption__ ?*size*? + + Specifies the *size* of the top caption region as the number rows it + occupies in the matrix to be formatted. Only numbers greater than or equal + to zero are allowed. If no *size* is specified the command will return the + current size instead. + + Setting the size of the top caption to a value greater than zero enables the + corresponding data template and causes the report to check all used + templates for inconsistencies in the definition of the vertical lines (See + section [TEMPLATES](#section4)). + + - *reportName* __bcaption__ *size* + + Specifies the *size* of the bottom caption region as the number rows it + occupies in the matrix to be formatted. Only numbers greater than or equal + to zero are allowed. If no *size* is specified the command will return the + current size instead. + + Setting the size of the bottom caption to a value greater than zero enables + the corresponding data template and causes the report to check all used + templates for inconsistencies in the definition of the vertical lines (See + section [TEMPLATES](#section4)). + + - *reportName* __size__ *column* ?*number*|__dyn__? + + Specifies the size of the *column* in the output. The value __dyn__ means + that the columnwidth returned by the matrix to be formatted for the + specified column shall be used. The formatting of the column is dynamic. If + a fixed *number* is used instead of __dyn__ it means that the column has a + width of that many characters (padding excluded). Only numbers greater than + zero are allowed here. + + If no size specification is given the command will return the current size + of the *column* instead. + + - *reportName* __sizes__ ?*size-list*? + + This method allows the user to specify the sizes of all columns in one call. + Its argument is a list containing the sizes to associate with the columns. + The first item is associated with column 0, the next with column 1, and so + on. + + If no *size-list* is specified the command will return a list containing the + currently set sizes instead. + + - *reportName* __pad__ *column* ?__left__|__right__|__both__ ?*padstring*?? + + This method allows the user to specify padding on the left, right or both + sides of a *column*. If the *padstring* is not specified it defaults to a + single space character. *Note*: An alternative way of specifying the padding + is to use vertical separator strings longer than one character in the + templates (See section [TEMPLATES](#section4)). + + If no pad specification is given at all the command will return the current + state of padding for the column instead. This will be a list containing two + elements, the first element the left padding, the second describing the + right padding. + + - *reportName* __justify__ *column* ?__left__|__right__|__center__? + + Declares how the cell values for a *column* are filled into the report given + the specified size of a column in the report. + + For __left__ and __right__ justification a cell value shorter than the width + of the column is bound with its named edge to the same edge of the column. + The other side is filled with spaces. In the case of __center__ the spaces + are placed to both sides of the value and the left number of spaces is at + most one higher than the right number of spaces. + + For a value longer than the width of the column the value is cut at the + named edge. This means for __left__ justification that the *tail* (i.e. the + __right__ part) of the value is made visible in the output. For __center__ + the value is cut at both sides to fit into the column and the number of + characters cut at the left side of the value is at most one less than the + number of characters cut from the right side. + + If no justification was specified the command will return the current + justification for the column instead. + + - *reportName* __printmatrix__ *matrix* + + Formats the *matrix* according to the configuration of the report and + returns the resulting string. The matrix has to have the same number of + columns as the report. The matrix also has to have enough rows so that the + top and bottom caption regions do not overlap. The data region is allowed to + be empty. + + - *reportName* __printmatrix2channel__ *matrix chan* + + Formats the *matrix* according to the configuration of the report and writes + the result into the channel *chan*. The matrix has to have the same number + of columns as the report. The matrix also has to have enough rows so that + the top and bottom caption regions do not overlap. The data region is + allowed to be empty. + + - *reportName* __[columns](../../../../index.md#columns)__ + + Returns the number of columns in the report. + +The methods __size__, __pad__ and __justify__ all take a column index as their +first argument. This index is allowed to use all the forms of an index as +accepted by the __lindex__ command. The allowed range for indices is +"0,...,[__reportName__ columns]-1". + +# EXAMPLES + +Our examples define some generally useful report styles. + +A simple table with lines surrounding all information and vertical separators, +but without internal horizontal separators. + + ::report::defstyle simpletable {} { + data set [split "[string repeat "| " [columns]]|"] + top set [split "[string repeat "+ - " [columns]]+"] + bottom set [top get] + top enable + bottom enable + } + +An extension of a __simpletable__, see above, with a title area. + + ::report::defstyle captionedtable {{n 1}} { + simpletable + topdata set [data get] + topcapsep set [top get] + topcapsep enable + tcaption $n + } + +Given the definitions above now an example which actually formats a matrix into +a tabular report. It assumes that the matrix actually contains useful data. + + % ::struct::matrix m + % # ... fill m with data, assume 5 columns + % ::report::report r 5 style captionedtable 1 + % r printmatrix m + +---+-------------------+-------+-------+--------+ + |000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%| + +---+-------------------+-------+-------+--------+ + |001|CATCH return ok |7 |13 |53.85 | + |002|CATCH return error |68 |91 |74.73 | + |003|CATCH no catch used|7 |14 |50.00 | + |004|IF if true numeric |12 |33 |36.36 | + |005|IF elseif |15 |47 |31.91 | + | |true numeric | | | | + +---+-------------------+-------+-------+--------+ + % + % # alternate way of doing the above + % m format 2string r + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *report* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[matrix](../../../../index.md#matrix), [report](../../../../index.md#report), +[table](../../../../index.md#table) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2002-2014 Andreas Kupries ADDED embedded/md/tcllib/files/modules/rest/rest.md Index: embedded/md/tcllib/files/modules/rest/rest.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/rest/rest.md @@ -0,0 +1,567 @@ + +[//000000001]: # (rest - A framework for RESTful web services) +[//000000002]: # (Generated from file 'rest.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (rest(n) 1.3.1 tcllib "A framework for RESTful web services") + +# NAME + +rest - define REST web APIs and call them inline or asychronously + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Simple usage](#section2) + + - [Interface usage](#section3) + + - [Examples](#section4) + + - [INCLUDED](#section5) + + - [TLS](#section6) + + - [TLS Security Considerations](#section7) + + - [Bugs, Ideas, Feedback](#section8) + +# SYNOPSIS + +package require Tcl 8.5 +package require rest ?1.3.1? + +[__::rest::simple__ *url* *query* ?*config*? ?*body*?](#1) +[__::rest::get__ *url* *query* ?*config*? ?*body*?](#2) +[__::rest::post__ *url* *query* ?*config*? ?*body*?](#3) +[__::rest::patch__ *url* *query* ?*config*? ?*body*?](#4) +[__::rest::head__ *url* *query* ?*config*? ?*body*?](#5) +[__::rest::put__ *url* *query* ?*config*? ?*body*?](#6) +[__::rest::delete__ *url* *query* ?*config*? ?*body*?](#7) +[__::rest::save__ *name* *file*](#8) +[__::rest::describe__ *name*](#9) +[__::rest::parameters__ *url* ?*key*?](#10) +[__::rest::parse_opts__ *static* *required* *optional* *words*](#11) +[__::rest::substitute__ *string* *var*](#12) +[__::rest::create_interface__ *name*](#13) + +# DESCRIPTION + +There are two types of usage this package supports: *simple calls*, and complete +*interfaces*. In an *interface* you specify a set of rules and then the package +builds the commands which correspond to the REST methods. These commands can +have many options such as input and output transformations and data type +specific formatting. This results in a cleaner and simpler script. On the other +hand, while a *simple call* is easier and quicker to implement it is also less +featureful. It takes the url and a few options about the command and returns the +result directly. Any formatting or checking is up to rest of the script. + +# Simple usage + +In simple usage you make calls using the http method procedures and then check +or process the returned data yourself + + - __::rest::simple__ *url* *query* ?*config*? ?*body*? + + - __::rest::get__ *url* *query* ?*config*? ?*body*? + + - __::rest::post__ *url* *query* ?*config*? ?*body*? + + - __::rest::patch__ *url* *query* ?*config*? ?*body*? + + - __::rest::head__ *url* *query* ?*config*? ?*body*? + + - __::rest::put__ *url* *query* ?*config*? ?*body*? + + - __::rest::delete__ *url* *query* ?*config*? ?*body*? + + These commands are all equivalent except for the http method used. If you + use __simple__ then the method should be specified as an option in the + *config* dictionary. If that is not done it defaults to __get__. If a *body* + is needed then the *config* dictionary must be present, however it is + allowed to be empty. + + The *config* dictionary supports the following keys + + * __auth__ + + * __content-type__ + + * __cookie__ + + * __error-body__ + + * __format__ + + * __headers__ + + * __method__ + + Two quick examples: + + Example 1, Yahoo Boss: + + set appid APPID + set search tcl + set res [rest::get http://boss.yahooapis.com/ysearch/web/v1/$search [list appid $appid]] + set res [rest::format_json $res] + + Example 2, Twitter: + + set url http://twitter.com/statuses/update.json + set query [list status $text] + set res [rest::simple $url $query { + method post + auth {basic user password} + format json + }] + +# Interface usage + +An interface to a REST API consists of a series of definitions of REST calls +contained in an array. The name of that array becomes a namespace containing the +defined commands. Each key of the array specifies the name of the call, with the +associated configuration a dictionary, i.e. key/value pairs. The acceptable +keys, i.e. legal configuration options are described below. After creating the +definitions in the array simply calling __rest::create_interface__ with the +array as argument will then create the desired commands. + +Example, Yahoo Weather: + + package require rest + + set yweather(forecast) { + url http://weather.yahooapis.com/forecastrss + req_args { p: } + opt_args { u: } + } + rest::create_interface yweather + puts [yweather::forecast -p 94089] + + - __::rest::save__ *name* *file* + + This command saves a copy of the dynamically created procedures for all the + API calls specified in the array variable *name* to the *file*, for later + loading. + + The result of the command is the empty string + + - __::rest::describe__ *name* + + This command prints a description of all API calls specified in the array + variable *name* to the channel __stdout__. + + The result of the command is the empty string. + + - __::rest::parameters__ *url* ?*key*? + + This command parses an *url* query string into a dictionary and returns said + dictionary as its result. + + If *key* is specified the command will not return the entire dictionary, but + only the value of that *key*. + + - __::rest::parse_opts__ *static* *required* *optional* *words* + + This command implements a custom parserfor command options. + + * dict *static* + + A dictionary of options and their values that are always present in the + output. + + * list *required* + + A list of options that must be supplied by *words* + + * list *optional* + + A list of options that may appear in the *words*, but are not required. + The elements must be in one of three forms: + + + name + + The option may be present or not, no default. + + + name: + + When present the option requires an argument. + + + name:value + + When not present use __value__ as default. + + * list *words* + + The words to parse into options and values. + + The result of the command is a list containing two elements. The first + element is a dictionary containing the parsed options and their values. The + second element is a list of the remaining words. + + - __::rest::substitute__ *string* *var* + + This command takes a *string*, substitutes values for any option identifiers + found inside and returns the modified string as its results. + + The values to substitute are found in the variable *var*, which is expected + to contain a dictionary mapping from the option identifiers to replace to + their values. *Note* that option identifiers which have no key in *var* are + replaced with the empty string. + + The option identifiers in *string* have to follow the syntax __%...%__ where + __...__ may contain any combination of lower-case alphanumeric characters, + plus underscore, colon and dash. + + - __::rest::create_interface__ *name* + + This command creates procedures for all the API calls specified in the array + variable *name*. + + The name of that array becomes a namespace containing the defined commands. + Each key of the array specifies the name of the call, with the associated + configuration a dictionary, i.e. key/value pairs. The legal keys and their + meanings are: + + * __url__ + + The value of this *required* option must be the target of the http + request. + + * __description__ + + The value of this option must be a short string describing the call. + Default to the empty string, if not specified. Used only by + __::rest::describe__. + + * __body__ + + The value of this option indicates if arguments are required for the + call's request body or not. The acceptable values are listed below. + Defaults to __optional__ if not specified. + + + __none__ + + The call has no request body, none must be supplied. + + + __optional__ + + A request body can be supplied, but is not required. + + + __required__ + + A request body must be supplied. + + + __argument__ + + This value must be followed by the name of an option, treating the + entire string as a list. The request body will be used as the value + of that option. + + + __mime_multipart__ + + A request body must be supplied and will be interpreted as each + argument representing one part of a mime/multipart document. + Arguments must be lists containing 2 elements, a list of header keys + and values, and the mime part body, in this order. + + * __method__ + + The value of this option must be the name of the HTTP method to call on + the url. Defaults to GET, if not specified. The acceptable values are + __GET__, __POST__, and __PUT__, regardless of letter-case. + + * __copy__ + + When present the value of this option specifies the name of a previously + defined call. The definition of that call is copied to the current call, + except for the options specified by the current call itself. + + * __unset__ + + When present the value of this option contains a list of options in the + current call. These options are removed from the definition. Use this + after __copy__ing an existing definition to remove options, instead of + overriding their value. + + * __headers__ + + Specification of additional header fields. The value of this option must + be a dictionary, interpreted to contain the new header fields and their + values. The default is to not add any additional headers. + + * __content-type__ + + The value of this option specifies the content type for the request + data. + + * __req_args__ + + The value of this option is a list naming the required arguments of the + call. Names ending in a colon will require a value. + + * __opt_args__ + + The value of this option a list naming the arguments that may be present + for a call but are not required. + + * __static_args__ + + The value of this option a list naming the arguments that are always the + same. No sense in troubling the user with these. A leading dash (__-__) + is allowed but not required to maintain consistency with the command + line. + + * __auth__ + + The value of this option specifies how to authenticate the calls. No + authentication is done if the option is not specified. + + + __basic__ + + The user may configure the *basic authentication* by overriding the + procedure __basic_auth__ in the namespace of interface. This + procedure takes two arguments, the username and password, in this + order. + + + __sign__ + + The value must actually be a list with the second element the name + of a procedure which will be called to perform request signing. + + * __callback__ + + If this option is present then the method will be created as an *async* + call. Such calls will return immediately with the value of the + associated http token instead of the call's result. The event loop must + be active to use this option. + + The value of this option is treated as a command prefix which is invoked + when the HTTP call is complete. The prefix will receive at least two + additional arguments, the name of the calling procedure and the status + of the result (one of __OK__ or __ERROR__), in this order. + + In case of __OK__ a third argument is added, the data associated with + the result. + + If and only if the __ERROR__ is a redirection, the location redirected + to will be added as argument. Further, if the configuration key + __error-body__ is set to __true__ the data associated with the result + will be added as argument as well. + + The http request header will be available in that procedure via __upvar + token token__. + + * __cookie__ + + The value of this option is a list of cookies to be passed in the http + header. This is a shortcut to the __headers__ option. + + * __input_transform__ + + The value of this option is a command prefix or script to perform a + transformation on the query before invoking the call. A script transform + is wrapped into an automatically generated internal procedure. + + If not specified no transformation is done. + + The command (prefix) must accept a single argument, the query (a + dictionary) to transform, and must return the modified query (again as + dictionary) as its result. The request body is accessible in the + transform command via __upvar body body__. + + * __format__ + + * __result__ + + The value of this option specifies the format of the returned data. + Defaults to __auto__ if not specified. The acceptable values are: + + + __auto__ + + Auto detect between __xml__ and __json__. + + + __discard__ + + + __json__ + + + __raw__ + + + __rss__ + + This is formatted as a special case of __xml__. + + + __tdom__ + + + __xml__ + + * __pre_transform__ + + The value of this option is a command prefix or script to perform a + transformation on the result of a call (*before* the application of the + output transform as per __format__). A script transform is wrapped into + an automatically generated internal procedure. + + If not specified no transformation is done. + + The command (prefix) must accept a single argument, the result to + transform, and must return the modified result as its result. + + The http request header is accessible in the transform command via + __upvar token token__ + + * __post_transform__ + + The value of this option is a command prefix or script to perform a + transformation on the result of a call (*after* the application of the + output transform as per __format__). A script transform is wrapped into + an automatically generated internal procedure. + + If not specified no transformation is done. + + The command (prefix) must accept a single argument, the result to + transform, and must return the modified result as its result. + + The http request header is accessible in the transform command via + __upvar token token__ + + * __check_result__ + + The value of this option must be list of two expressions, either of + which may be empty. + + The first expression is checks the OK condition, it must return __true__ + when the result is satisfactory, and __false__ otherwise. + + The second expression is the ERROR condition, it must return __false__ + unless there is an error, then it has to return __true__. + + * __error_body__ + + The value of this option determines whether to return the response when + encountering an HTTP error, or not. The default is to not return the + response body on error. + + See __callback__ above for more information. + +# Examples + +Yahoo Geo: + + set ygeo(parse) { + url http://wherein.yahooapis.com/v1/document + method post + body { arg documentContent } + } + ygeo::parse "san jose ca" + # "san jose ca" will be interpreted as if it were specified as the -documentContent option + +Google Docs: + + set gdocs(upload) { + url http://docs.google.com/feeds/default/private/full + body mime_multipart + } + gdocs::upload [list {Content-Type application/atom+xml} $xml] [list {Content-Type image/jpeg} $filedata] + +Delicious: + + set delicious(updated) { + url https://api.del.icio.us/v1/posts/update + auth basic + } + + rest::create_interface flickr + + flickr::basic_auth username password + +Flickr: + + set flickr(auth.getToken) { + url http://api.flickr.com/services/rest/ + req_args { api_key: secret: } + auth { sign do_signature } + } + + rest::create_interface flickr + + proc ::flickr::do_signature {query} { + # perform some operations on the query here + return $query + } + +# INCLUDED + +The package provides functional but incomplete implementations for the following +services: + + - __del.icio.us__ + + - __facebook__ + + - __flickr__ + + - __twitter__ + + - __google calendar__ + + - __yahoo boss__ + + - __yahoo weather__ + +Please either read the package's implementation, or use __rest::describe__ after +loading it for their details. + +Do not forget developers' documentation on the respective sites either. + +# TLS + +The __rest__ package can be used with +*[https](../../../../index.md#https)*-secured services, by requiring the +__[TLS](../../../../index.md#tls)__ package and then registering it with the +__[http](../../../../index.md#http)__ package it is sitting on top of. Example + + package require tls + http::register https 443 ::tls::socket + +# TLS Security Considerations + +This package uses the __[TLS](../../../../index.md#tls)__ package to handle the +security for __https__ urls and other socket connections. + +Policy decisions like the set of protocols to support and what ciphers to use +are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this +package itself however. Such decisions are the responsibility of whichever +application is using the package, and are likely influenced by the set of +servers the application will talk to as well. + +For example, in light of the recent [POODLE +attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html) +discovered by Google many servers will disable support for the SSLv3 protocol. +To handle this change the applications using __[TLS](../../../../index.md#tls)__ +must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__ +itself. Such a patch may be as simple as generally activating __tls1__ support, +as shown in the example below. + + package require tls + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol + + ... your own application code ... + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *rest* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. ADDED embedded/md/tcllib/files/modules/ripemd/ripemd128.md Index: embedded/md/tcllib/files/modules/ripemd/ripemd128.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/ripemd/ripemd128.md @@ -0,0 +1,207 @@ + +[//000000001]: # (ripemd128 - RIPEMD Message-Digest Algorithm) +[//000000002]: # (Generated from file 'ripemd128.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (ripemd128(n) 1.0.5 tcllib "RIPEMD Message-Digest Algorithm") + +# NAME + +ripemd128 - RIPEMD-128 Message-Digest Algorithm + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [PROGRAMMING INTERFACE](#section3) + + - [EXAMPLES](#section4) + + - [REFERENCES](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require ripemd128 ?1.0.5? + +[__::ripemd::ripemd128__ ?*-hex*? [ *-channel channel* | *-file filename* | *string* ]](#1) +[__::ripemd::hmac128__ ?*-hex*? *-key key* [ *-channel channel* | *-file filename* | *string* ]](#2) +[__::ripemd::RIPEMD128Init__](#3) +[__::ripemd::RIPEMD128Update__ *token* *data*](#4) +[__::ripemd::RIPEMD128Final__ *token*](#5) +[__::ripemd::RIPEHMAC128Init__ *key*](#6) +[__::ripemd::RIPEHMAC128Update__ *token* *data*](#7) +[__::ripemd::RIPEHMAC128Final__ *token*](#8) + +# DESCRIPTION + +This package is an implementation in Tcl of the RIPEMD-128 message-digest +algorithm (1). This algorithm takes an arbitrary quantity of data and generates +a 128-bit message digest from the input. The RIPEMD-128 algorithm is based upon +the MD4 algorithm (2, 4) but has been cryptographically strengthened against +weaknesses that have been found in MD4 (4). RIPEMD-128 has been designed to be a +drop-in replacement for MD4 and MD5 (5). If security is the major consideration, +then RIPEMD-160 or SHA1 should be considered. + +This package will use __Trf__ to accelerate the digest computation if available. +In the absence of an accelerator package the pure-Tcl implementation will be +used. + +# COMMANDS + + - __::ripemd::ripemd128__ ?*-hex*? [ *-channel channel* | *-file filename* | *string* ] + + Calculate the RIPEMD-128 digest of the data given in string. This is + returned as a binary string by default. Giving the *-hex* option will return + a hexadecimal encoded version of the digest. + + The data to be hashed can be specified either as a string argument to the + ripemd128 command, or as a filename or a pre-opened channel. If the + *-filename* argument is given then the file is opened, the data read and + hashed and the file is closed. If the *-channel* argument is given then data + is read from the channel until the end of file. The channel is not closed. + + Only one of *-file*, *-channel* or *string* should be given. + + - __::ripemd::hmac128__ ?*-hex*? *-key key* [ *-channel channel* | *-file filename* | *string* ] + + Calculate an Hashed Message Authentication digest (HMAC) using the + RIPEMD-128 digest algorithm. HMACs are described in RFC 2104 (6) and provide + a RIPEMD-128 digest that includes a key. All options other than *-key* are + as for the __::ripemd::ripemd128__ command. + +# PROGRAMMING INTERFACE + +For the programmer, hash functions can be viewed as a bucket into which one +pours data. When you have finished, you extract a value that is uniquely derived +from the data that was poured into the bucket. The programming interface to the +hash operates on a token (equivalent to the bucket). You call __RIPEMD128Init__ +to obtain a token and then call __RIPEMD128Update__ as many times as required to +add data to the hash. To release any resources and obtain the hash value, you +then call __RIPEMD128Final__. An equivalent set of functions gives you a keyed +digest (HMAC). + +If you have __critcl__ and have built the __tcllibc__ package then the +implementation of the hashing function will be performed by compiled code. +Alternatively if both the Trf and Memchan extensions are available then these +will be used. Finally the package will revert to a pure-Tcl implementation. The +programming interface remains the same, however. + + - __::ripemd::RIPEMD128Init__ + + Begins a new RIPEMD-128 hash. Returns a token ID that must be used for the + remaining functions. + + - __::ripemd::RIPEMD128Update__ *token* *data* + + Add data to the hash identified by token. Calling *RIPEMD128Update $token + "abcd"* is equivalent to calling *RIPEMD128Update $token "ab"* followed by + *RIPEMD128Update $token "cb"*. See [EXAMPLES](#section4). + + - __::ripemd::RIPEMD128Final__ *token* + + Returns the hash value and releases any resources held by this token. Once + this command completes the token will be invalid. The result is a binary + string of 16 bytes representing the 128 bit RIPEMD-128 digest value. + + - __::ripemd::RIPEHMAC128Init__ *key* + + This is equivalent to the __::ripemd::RIPEMD128Init__ command except that it + requires the key that will be included in the HMAC. + + - __::ripemd::RIPEHMAC128Update__ *token* *data* + + - __::ripemd::RIPEHMAC128Final__ *token* + + These commands are identical to the RIPEMD128 equivalent commands. + +# EXAMPLES + + % ripemd::ripemd128 -hex "Tcl does RIPEMD-128" + 3cab177bae65205d81e7978f63556c63 + + % ripemd::hmac128 -hex -key Sekret "Tcl does RIPEMD-128" + b359dc5971a05beea0be7b106b30e389 + + % set tok [ripemd::RIPEMD128Init] + ::ripemd::1 + % ripemd::RIPEMD128Update $tok "Tcl " + % ripemd::RIPEMD128Update $tok "does " + % ripemd::RIPEMD128Update $tok "RIPEMD-128" + % ripemd::Hex [ripemd::RIPEMD128Final $tok] + 3cab177bae65205d81e7978f63556c63 + +# REFERENCES + + 1. H. Dobbertin, A. Bosselaers, B. Preneel, "RIPEMD-160, a strengthened + version of RIPEMD" + [http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf](http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf) + + 1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992. + ([http://www.rfc-editor.org/rfc/rfc1320.txt](http://www.rfc-editor.org/rfc/rfc1320.txt)) + + 1. Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes and S.A. + Vanstone, editors, Advances in Cryptology - CRYPTO '90 Proceedings, pages + 303-311, Springer-Verlag, 1991. + + 1. Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology vol 11 (4), + pp. 253-271 (1998) + + 1. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and RSA Data + Security, Inc, April 1992. + ([http://www.rfc-editor.org/rfc/rfc1321.txt](http://www.rfc-editor.org/rfc/rfc1321.txt)) + + 1. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message + Authentication", RFC 2104, February 1997. + ([http://www.rfc-editor.org/rfc/rfc2104.txt](http://www.rfc-editor.org/rfc/rfc2104.txt)) + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *ripemd* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[md4](../md4/md4.md), [md5](../md5/md5.md), [ripemd160](ripemd160.md), +[sha1](../sha1/sha1.md) + +# KEYWORDS + +[RIPEMD](../../../../index.md#ripemd), [hashing](../../../../index.md#hashing), +[md4](../../../../index.md#md4), +[message-digest](../../../../index.md#message_digest), [rfc +1320](../../../../index.md#rfc_1320), [rfc 1321](../../../../index.md#rfc_1321), +[rfc 2104](../../../../index.md#rfc_2104), +[security](../../../../index.md#security) + +# CATEGORY + +Hashes, checksums, and encryption + +# COPYRIGHT + +Copyright © 2004, Pat Thoyts ADDED embedded/md/tcllib/files/modules/ripemd/ripemd160.md Index: embedded/md/tcllib/files/modules/ripemd/ripemd160.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/ripemd/ripemd160.md @@ -0,0 +1,195 @@ + +[//000000001]: # (ripemd160 - RIPEMD Message-Digest Algorithm) +[//000000002]: # (Generated from file 'ripemd160.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (ripemd160(n) 1.0.5 tcllib "RIPEMD Message-Digest Algorithm") + +# NAME + +ripemd160 - RIPEMD-160 Message-Digest Algorithm + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [PROGRAMMING INTERFACE](#section3) + + - [EXAMPLES](#section4) + + - [REFERENCES](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require ripemd160 ?1.0.5? + +[__::ripemd::ripemd160__ ?*-hex*? [ *-channel channel* | *-file filename* | *string* ]](#1) +[__::ripemd::hmac160__ ?*-hex*? *-key key* [ *-channel channel* | *-file filename* | *string* ]](#2) +[__::ripemd::RIPEMD160Init__](#3) +[__::ripemd::RIPEMD160Update__ *token* *data*](#4) +[__::ripemd::RIPEMD160Final__ *token*](#5) +[__::ripemd::RIPEHMAC160Init__ *key*](#6) +[__::ripemd::RIPEHMAC160Update__ *token* *data*](#7) +[__::ripemd::RIPEHMAC160Final__ *token*](#8) + +# DESCRIPTION + +This package is an implementation in Tcl of the RIPEMD-160 message-digest +algorithm (1). This algorithm takes an arbitrary quantity of data and generates +a 160-bit message digest from the input. The RIPEMD-160 algorithm is based upon +the MD4 algorithm (2, 4) but has been cryptographically strengthened against +weaknesses that have been found in MD4 (4). + +This package will use __cryptkit__ or __Trf__ to accelerate the digest +computation if either package is available. In the absence of an accelerator +package the pure-Tcl implementation will be used. + +# COMMANDS + + - __::ripemd::ripemd160__ ?*-hex*? [ *-channel channel* | *-file filename* | *string* ] + + Calculate the RIPEMD-160 digest of the data given in string. This is + returned as a binary string by default. Giving the *-hex* option will return + a hexadecimal encoded version of the digest. + + The data to be hashed can be specified either as a string argument to the + ripemd160 command, or as a filename or a pre-opened channel. If the + *-filename* argument is given then the file is opened, the data read and + hashed and the file is closed. If the *-channel* argument is given then data + is read from the channel until the end of file. The channel is not closed. + + Only one of *-file*, *-channel* or *string* should be given. + + - __::ripemd::hmac160__ ?*-hex*? *-key key* [ *-channel channel* | *-file filename* | *string* ] + + Calculate an Hashed Message Authentication digest (HMAC) using the + RIPEMD-160 digest algorithm. HMACs are described in RFC 2104 (5) and provide + a RIPEMD-160 digest that includes a key. All options other than *-key* are + as for the __::ripemd::ripemd160__ command. + +# PROGRAMMING INTERFACE + +For the programmer, hash functions can be viewed as a bucket into which one +pours data. When you have finished, you extract a value that is uniquely derived +from the data that was poured into the bucket. The programming interface to the +hash operates on a token (equivalent to the bucket). You call __RIPEMD160Init__ +to obtain a token and then call __RIPEMD160Update__ as many times as required to +add data to the hash. To release any resources and obtain the hash value, you +then call __RIPEMD160Final__. An equivalent set of functions gives you a keyed +digest (HMAC). + + - __::ripemd::RIPEMD160Init__ + + Begins a new RIPEMD-160 hash. Returns a token ID that must be used for the + remaining functions. + + - __::ripemd::RIPEMD160Update__ *token* *data* + + Add data to the hash identified by token. Calling *RIPEMD160Update $token + "abcd"* is equivalent to calling *RIPEMD160Update $token "ab"* followed by + *RIPEMD160Update $token "cb"*. See [EXAMPLES](#section4). + + - __::ripemd::RIPEMD160Final__ *token* + + Returns the hash value and releases any resources held by this token. Once + this command completes the token will be invalid. The result is a binary + string of 16 bytes representing the 160 bit RIPEMD-160 digest value. + + - __::ripemd::RIPEHMAC160Init__ *key* + + This is equivalent to the __::ripemd::RIPEMD160Init__ command except that it + requires the key that will be included in the HMAC. + + - __::ripemd::RIPEHMAC160Update__ *token* *data* + + - __::ripemd::RIPEHMAC160Final__ *token* + + These commands are identical to the RIPEMD160 equivalent commands. + +# EXAMPLES + + % ripemd::ripemd160 -hex "Tcl does RIPEMD-160" + 0829dea75a1a7074c702896723fe37763481a0a7 + + % ripemd::hmac160 -hex -key Sekret "Tcl does RIPEMD-160" + bf0c927231733686731dddb470b64a9c23f7f53b + + % set tok [ripemd::RIPEMD160Init] + ::ripemd::1 + % ripemd::RIPEMD160Update $tok "Tcl " + % ripemd::RIPEMD160Update $tok "does " + % ripemd::RIPEMD160Update $tok "RIPEMD-160" + % ripemd::Hex [ripemd::RIPEMD160Final $tok] + 0829dea75a1a7074c702896723fe37763481a0a7 + +# REFERENCES + + 1. H. Dobbertin, A. Bosselaers, B. Preneel, "RIPEMD-160, a strengthened + version of RIPEMD" + [http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf](http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf) + + 1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992. + ([http://www.rfc-editor.org/rfc/rfc1320.txt](http://www.rfc-editor.org/rfc/rfc1320.txt)) + + 1. Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes and S.A. + Vanstone, editors, Advances in Cryptology - CRYPTO '90 Proceedings, pages + 303-311, Springer-Verlag, 1991. + + 1. Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology vol 11 (4), + pp. 253-271 (1998) + + 1. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message + Authentication", RFC 2104, February 1997. + ([http://www.rfc-editor.org/rfc/rfc2104.txt](http://www.rfc-editor.org/rfc/rfc2104.txt)) + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *ripemd* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[md4](../md4/md4.md), [md5](../md5/md5.md), [ripemd128](ripemd128.md), +[sha1](../sha1/sha1.md) + +# KEYWORDS + +[RIPEMD](../../../../index.md#ripemd), [hashing](../../../../index.md#hashing), +[md4](../../../../index.md#md4), +[message-digest](../../../../index.md#message_digest), [rfc +1320](../../../../index.md#rfc_1320), [rfc 1321](../../../../index.md#rfc_1321), +[rfc 2104](../../../../index.md#rfc_2104), +[security](../../../../index.md#security) + +# CATEGORY + +Hashes, checksums, and encryption + +# COPYRIGHT + +Copyright © 2004, Pat Thoyts ADDED embedded/md/tcllib/files/modules/sasl/gtoken.md Index: embedded/md/tcllib/files/modules/sasl/gtoken.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/sasl/gtoken.md @@ -0,0 +1,97 @@ + +[//000000001]: # (SASL::XGoogleToken - Simple Authentication and Security Layer (SASL)) +[//000000002]: # (Generated from file 'gtoken.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (SASL::XGoogleToken(n) 1.0.1 tcllib "Simple Authentication and Security Layer (SASL)") + +# NAME + +SASL::XGoogleToken - Implementation of SASL NTLM mechanism for Tcl + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [TLS Security Considerations](#section2) + + - [AUTHORS](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require SASL::XGoogleToken ?1.0.1? + +# DESCRIPTION + +This package provides the XGoogleToken authentication mechanism for the Simple +Authentication and Security Layer (SASL). + +Please read the documentation for package __sasl__ for details. + +# TLS Security Considerations + +This package uses the __[TLS](../../../../index.md#tls)__ package to handle the +security for __https__ urls and other socket connections. + +Policy decisions like the set of protocols to support and what ciphers to use +are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this +package itself however. Such decisions are the responsibility of whichever +application is using the package, and are likely influenced by the set of +servers the application will talk to as well. + +For example, in light of the recent [POODLE +attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html) +discovered by Google many servers will disable support for the SSLv3 protocol. +To handle this change the applications using __[TLS](../../../../index.md#tls)__ +must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__ +itself. Such a patch may be as simple as generally activating __tls1__ support, +as shown in the example below. + + package require tls + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol + + ... your own application code ... + +# AUTHORS + +Pat Thoyts + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *sasl* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[SASL](../../../../index.md#sasl), +[XGoogleToken](../../../../index.md#xgoogletoken), +[authentication](../../../../index.md#authentication) + +# CATEGORY + +Networking + +# COPYRIGHT + +Copyright © 2006, Pat Thoyts ADDED embedded/md/tcllib/files/modules/sasl/ntlm.md Index: embedded/md/tcllib/files/modules/sasl/ntlm.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/sasl/ntlm.md @@ -0,0 +1,78 @@ + +[//000000001]: # (SASL::NTLM - Simple Authentication and Security Layer (SASL)) +[//000000002]: # (Generated from file 'ntlm.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (SASL::NTLM(n) 1.1.2 tcllib "Simple Authentication and Security Layer (SASL)") + +# NAME + +SASL::NTLM - Implementation of SASL NTLM mechanism for Tcl + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [REFERENCES](#section2) + + - [AUTHORS](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require SASL::NTLM ?1.1.2? + +# DESCRIPTION + +This package provides the NTLM authentication mechanism for the Simple +Authentication and Security Layer (SASL). + +Please read the documentation for package __sasl__ for details. + +# REFERENCES + + 1. No official specification is available. However, + [http://davenport.sourceforge.net/ntlm.html](http://davenport.sourceforge.net/ntlm.html) + provides a good description. + +# AUTHORS + +Pat Thoyts + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *sasl* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[NTLM](../../../../index.md#ntlm), [SASL](../../../../index.md#sasl), +[authentication](../../../../index.md#authentication) + +# CATEGORY + +Networking + +# COPYRIGHT + +Copyright © 2005-2006, Pat Thoyts ADDED embedded/md/tcllib/files/modules/sasl/sasl.md Index: embedded/md/tcllib/files/modules/sasl/sasl.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/sasl/sasl.md @@ -0,0 +1,361 @@ + +[//000000001]: # (SASL - Simple Authentication and Security Layer (SASL)) +[//000000002]: # (Generated from file 'sasl.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (SASL(n) 1.3.3 tcllib "Simple Authentication and Security Layer (SASL)") + +# NAME + +SASL - Implementation of SASL mechanisms for Tcl + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [OPTIONS](#section3) + + - [CALLBACK PROCEDURE](#section4) + + - [MECHANISMS](#section5) + + - [EXAMPLES](#section6) + + - [REFERENCES](#section7) + + - [AUTHORS](#section8) + + - [Bugs, Ideas, Feedback](#section9) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require SASL ?1.3.3? + +[__::SASL::new__ *option value ?...?*](#1) +[__::SASL::configure__ *option value* ?*...*?](#2) +[__::SASL::step__ *context* *challenge* ?*...*?](#3) +[__::SASL::response__ *context*](#4) +[__::SASL::reset__ *context*](#5) +[__::SASL::cleanup__ *context*](#6) +[__::SASL::mechanisms__ ?*type*? ?*minimum*?](#7) +[__::SASL::register__ *mechanism* *preference* *clientproc* ?*serverproc*?](#8) + +# DESCRIPTION + +The Simple Authentication and Security Layer (SASL) is a framework for providing +authentication and authorization to comunications protocols. The SASL framework +is structured to permit negotiation among a number of authentication mechanisms. +SASL may be used in SMTP, IMAP and HTTP authentication. It is also in use in +XMPP, LDAP and BEEP. See [MECHANISMS](#section5) for the set of available SASL +mechanisms provided with tcllib. + +The SASL framework operates using a simple multi-step challenge response +mechanism. All the mechanisms work the same way although the number of steps may +vary. In this implementation a callback procedure must be provided from which +the SASL framework will obtain users details. See [CALLBACK +PROCEDURE](#section4) for details of this procedure. + +# COMMANDS + + - __::SASL::new__ *option value ?...?* + + Contruct a new SASL context. See [OPTIONS](#section3) for details of the + possible options to this command. A context token is required for most of + the SASL procedures. + + - __::SASL::configure__ *option value* ?*...*? + + Modify and inspect the SASL context option. See [OPTIONS](#section3) for + further details. + + - __::SASL::step__ *context* *challenge* ?*...*? + + This is the core procedure for using the SASL framework. The __step__ + procedure should be called until it returns 0. Each step takes a server + challenge string and the response is calculated and stored in the context. + Each mechanism may require one or more steps. For some steps there may be no + server challenge required in which case an empty string should be provided + for this parameter. All mechanisms should accept an initial empty challenge. + + - __::SASL::response__ *context* + + Returns the next response string that should be sent to the server. + + - __::SASL::reset__ *context* + + Re-initialize the SASL context. Discards any internal state and permits the + token to be reused. + + - __::SASL::cleanup__ *context* + + Release all resources associated with the SASL context. The context token + may not be used again after this procedure has been called. + + - __::SASL::mechanisms__ ?*type*? ?*minimum*? + + Returns a list of all the available SASL mechanisms. The list is sorted by + the mechanism preference value (see __register__) with the preferred + mechanisms and the head of the list. Any mechanism with a preference value + less than the*minimum* (which defaults to 0) is removed from the returned + list. This permits a security threshold to be set. Mechanisms with a + preference less that 25 transmit authentication are particularly susceptible + to eavesdropping and should not be provided unless a secure channel is in + use (eg: tls). + + The *type* parameter may be one of *client* or *server* and defaults to + *client*. Only mechanisms that have an implementation matching the *type* + are returned (this permits servers to correctly declare support only for + mechanisms that actually provide a server implementation). + + - __::SASL::register__ *mechanism* *preference* *clientproc* ?*serverproc*? + + New mechanisms can be added to the package by registering the mechanism name + and the implementing procedures. The server procedure is optional. The + preference value is an integer that is used to order the list returned by + the __mechanisms__ command. Higher values indicate a preferred mechanism. If + the mechanism is already registered then the recorded values are updated. + +# OPTIONS + + - __-callback__ + + Specify a command to be evaluated when the SASL mechanism requires + information about the user. The command is called with the current SASL + context and a name specifying the information desired. See + [EXAMPLES](#section6). + + - __-mechanism__ + + Set the SASL mechanism to be used. See __mechanisms__ for a list of + supported authentication mechanisms. + + - __-service__ + + Set the service type for this context. Some mechanisms may make use of this + parameter (eg DIGEST-MD5, GSSAPI and Kerberos). If not set it defaults to an + empty string. If the __-type__ is set to 'server' then this option should be + set to a valid service identity. Some examples of valid service names are + smtp, ldap, beep and xmpp. + + - __-server__ + + This option is used to set the server name used in SASL challenges when + operating as a SASL server. + + - __-type__ + + The context type may be one of 'client' or 'server'. The default is to + operate as a client application and respond to server challenges. Mechanisms + may be written to support server-side SASL and setting this option will + cause each __step__ to issue the next challenge. A new context must be + created for each incoming client connection when in server mode. + +# CALLBACK PROCEDURE + +When the SASL framework requires any user details it will call the procedure +provided when the context was created with an argument that specfies the item of +information required. + +In all cases a single response string should be returned. + + - login + + The callback procedure should return the users authorization identity. + Return an empty string unless this is to be different to the authentication + identity. Read [1] for a discussion about the specific meaning of + authorization and authentication identities within SASL. + + - username + + The callback procedure should return the users authentication identity. Read + [1] for a discussion about the specific meaning of authorization and + authentication identities within SASL. + + - password + + The callback procedure should return the password that matches the + authentication identity as used within the current realm. + + For server mechanisms the password callback should always be called with the + authentication identity and the realm as the first two parameters. + + - realm + + Some SASL mechanisms use realms to partition authentication identities. The + realm string is protocol dependent and is often the current DNS domain or in + the case of the NTLM mechanism it is the Windows NT domain name. + + - hostname + + Returns the client host name - typically [info host]. + +# MECHANISMS + + - ANONYMOUS + + As used in FTP this mechanism only passes an email address for + authentication. The ANONYMOUS mechanism is specified in [2]. + + - PLAIN + + This is the simplest mechanism. The users authentication details are + transmitted in plain text. This mechanism should not be provided unless an + encrypted link is in use - typically after SSL or TLS has been negotiated. + + - LOGIN + + The LOGIN [1] mechanism transmits the users details with base64 encoding. + This is no more secure than PLAIN and likewise should not be used without a + secure link. + + - CRAM-MD5 + + This mechanism avoids sending the users password over the network in plain + text by hashing the password with a server provided random value (known as a + nonce). A disadvantage of this mechanism is that the server must maintain a + database of plaintext passwords for comparison. CRAM-MD5 was defined in [4]. + + - DIGEST-MD5 + + This mechanism improves upon the CRAM-MD5 mechanism by avoiding the need for + the server to store plaintext passwords. With digest authentication the + server needs to store the MD5 digest of the users password which helps to + make the system more secure. As in CRAM-MD5 the password is hashed with a + server nonce and other data before being transmitted across the network. + Specified in [3]. + + - OTP + + OTP is the One-Time Password system described in RFC 2289 [6]. This + mechanism is secure against replay attacks and also avoids storing password + or password equivalents on the server. Only a digest of a seed and a + passphrase is ever transmitted across the network. Requires the + __[otp](../otp/otp.md)__ package from tcllib and one or more of the + cryptographic digest packages (md5 or sha-1 are the most commonly used). + + - NTLM + + This is a proprietary protocol developed by Microsoft [5] and is in common + use for authenticating users in a Windows network environment. NTLM uses DES + encryption and MD4 digests of the users password to authenticate a + connection. Certain weaknesses have been found in NTLM and thus there are a + number of versions of the protocol. As this mechanism has additional + dependencies it is made available as a separate sub-package. To enable this + mechanism your application must load the __[SASL::NTLM](ntlm.md)__ package. + + - X-GOOGLE-TOKEN + + This is a proprietary protocol developed by Google and used for + authenticating users for the Google Talk service. This mechanism makes a + pair of HTTP requests over an SSL channel and so this mechanism depends upon + the availability of the tls and http packages. To enable this mechanism your + application must load the __[SASL::XGoogleToken](gtoken.md)__ package. In + addition you are recommended to make use of the autoproxy package to handle + HTTP proxies reasonably transparently. + + - SCRAM + + This is a protocol specified in RFC 5802 [7]. To enable this mechanism your + application must load the __[SASL::SCRAM](scram.md)__ package. + +# EXAMPLES + +See the examples subdirectory for more complete samples using SASL with network +protocols. The following should give an idea how the SASL commands are to be +used. In reality this should be event driven. Each time the __step__ command is +called, the last server response should be provided as the command argument so +that the SASL mechanism can take appropriate action. + + proc ClientCallback {context command args} { + switch -exact -- $command { + login { return "" } + username { return $::tcl_platform(user) } + password { return "SecRet" } + realm { return "" } + hostname { return [info host] } + default { return -code error unxpected } + } + } + + proc Demo {{mech PLAIN}} { + set ctx [SASL::new -mechanism $mech -callback ClientCallback] + set challenge "" + while {1} { + set more_steps [SASL::step $ctx challenge] + puts "Send '[SASL::response $ctx]'" + puts "Read server response into challenge var" + if {!$more_steps} {break} + } + SASL::cleanup $ctx + } + +# REFERENCES + + 1. Myers, J. "Simple Authentication and Security Layer (SASL)", RFC 2222, + October 1997. + ([http://www.ietf.org/rfc/rfc2222.txt](http://www.ietf.org/rfc/rfc2222.txt)) + + 1. Newman, C. "Anonymous SASL Mechanism", RFC 2245, November 1997. + ([http://www.ietf.org/rfc/rfc2245.txt](http://www.ietf.org/rfc/rfc2245.txt)) + + 1. Leach, P., Newman, C. "Using Digest Authentication as a SASL Mechanism", + RFC 2831, May 2000, + ([http://www.ietf.org/rfc/rfc2831.txt](http://www.ietf.org/rfc/rfc2831.txt)) + + 1. Klensin, J., Catoe, R. and Krumviede, P., "IMAP/POP AUTHorize Extension for + Simple Challenge/Response" RFC 2195, September 1997. + ([http://www.ietf.org/rfc/rfc2195.txt](http://www.ietf.org/rfc/rfc2195.txt)) + + 1. No official specification is available. However, + [http://davenport.sourceforge.net/ntlm.html](http://davenport.sourceforge.net/ntlm.html) + provides a good description. + + 1. Haller, N. et al., "A One-Time Password System", RFC 2289, February 1998, + ([http://www.ieft.org/rfc/rfc2289.txt](http://www.ieft.org/rfc/rfc2289.txt)) + + 1. Newman, C. et al., "Salted Challenge Response Authentication Mechanism + (SCRAM) SASL and GSS-API Mechanisms", RFC 5802, July 2010, + ([http://www.ieft.org/rfc/rfc5802.txt](http://www.ieft.org/rfc/rfc5802.txt)) + +# AUTHORS + +Pat Thoyts + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *sasl* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[SASL](../../../../index.md#sasl), +[authentication](../../../../index.md#authentication) + +# CATEGORY + +Networking + +# COPYRIGHT + +Copyright © 2005-2006, Pat Thoyts ADDED embedded/md/tcllib/files/modules/sasl/scram.md Index: embedded/md/tcllib/files/modules/sasl/scram.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/sasl/scram.md @@ -0,0 +1,78 @@ + +[//000000001]: # (SASL::SCRAM - Simple Authentication and Security Layer (SASL)) +[//000000002]: # (Generated from file 'scram.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (SASL::SCRAM(n) 0.1 tcllib "Simple Authentication and Security Layer (SASL)") + +# NAME + +SASL::SCRAM - Implementation of SASL SCRAM mechanism for Tcl + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [REFERENCES](#section2) + + - [AUTHORS](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require SASL::SCRAM ?0.1? + +# DESCRIPTION + +This package provides the SCRAM authentication mechanism for the Simple +Authentication and Security Layer (SASL). + +Please read the documentation for package __sasl__ for details. + +# REFERENCES + + 1. Newman, C. et al., "Salted Challenge Response Authentication Mechanism + (SCRAM) SASL and GSS-API Mechanisms", RFC 5802, July 2010, + ([http://www.ieft.org/rfc/rfc5802.txt](http://www.ieft.org/rfc/rfc5802.txt)) + +# AUTHORS + +Sergei Golovan + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *sasl* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[SASL](../../../../index.md#sasl), [SCRAM](../../../../index.md#scram), +[authentication](../../../../index.md#authentication) + +# CATEGORY + +Networking + +# COPYRIGHT + +Copyright © 2013 Sergei Golovan ADDED embedded/md/tcllib/files/modules/sha1/sha1.md Index: embedded/md/tcllib/files/modules/sha1/sha1.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/sha1/sha1.md @@ -0,0 +1,207 @@ + +[//000000001]: # (sha1 - SHA-x Message-Digest Algorithm) +[//000000002]: # (Generated from file 'sha1.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (sha1(n) 2.0.3 tcllib "SHA-x Message-Digest Algorithm") + +# NAME + +sha1 - SHA1 Message-Digest Algorithm + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [PROGRAMMING INTERFACE](#section3) + + - [EXAMPLES](#section4) + + - [REFERENCES](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require sha1 ?2.0.3? + +[__::sha1::sha1__ ?__-hex|-bin__? [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]](#1) +[__::sha1::hmac__ *key* *string*](#2) +[__::sha1::hmac__ ?__-hex|-bin__? __-key key__ [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]](#3) +[__::sha1::SHA1Init__](#4) +[__::sha1::SHA1Update__ *token* *data*](#5) +[__::sha1::SHA1Final__ *token*](#6) +[__::sha1::HMACInit__ *key*](#7) +[__::sha1::HMACUpdate__ *token* *data*](#8) +[__::sha1::HMACFinal__ *token*](#9) + +# DESCRIPTION + +This package provides an implementation in Tcl of the SHA1 message-digest +algorithm as specified by FIPS PUB 180-1 (1). This algorithm takes a message and +generates a 160-bit digest from the input. The SHA1 algorithm is related to the +MD4 algorithm (2) but has been strengthend against certain types of +cryptographic attack. SHA1 should be used in preference to MD4 or MD5 in new +applications. + +This package also includes support for creating keyed message-digests using the +HMAC algorithm from RFC 2104 (3) with SHA1 as the message-digest. + +# COMMANDS + + - __::sha1::sha1__ ?__-hex|-bin__? [ __-channel channel__ | __-file filename__ | ?__--__? *string* ] + + The command takes a message and returns the SHA1 digest of this message as a + hexadecimal string. You may request the result as binary data by giving + *-bin*. + + The data to be hashed can be specified either as a string argument to the + __sha1__ command, or as a filename or a pre-opened channel. If the + *-filename* argument is given then the file is opened, the data read and + hashed and the file is closed. If the *-channel* argument is given then data + is read from the channel until the end of file. The channel is not closed. + *NOTE* use of the channel or filename options results in the internal use of + __[vwait](../../../../index.md#vwait)__. To avoid nested event loops in Tk + or tclhttpd applications you should use the incremental programming API (see + below). + + Only one of *-file*, *-channel* or *string* should be given. + + If the *string* to hash can be mistaken for an option (leading dash "-"), + use the option __--__ before it to terminate option processing and force + interpretation as a string. + + - __::sha1::hmac__ *key* *string* + + - __::sha1::hmac__ ?__-hex|-bin__? __-key key__ [ __-channel channel__ | __-file filename__ | ?__--__? *string* ] + + Calculate an Hashed Message Authentication digest (HMAC) using the SHA1 + digest algorithm. HMACs are described in RFC 2104 (3) and provide an SHA1 + digest that includes a key. All options other than *-key* are as for the + __::sha1::sha1__ command. + + If the *string* to hash can be mistaken for an option (leading dash "-"), + use the option __--__ before it to terminate option processing and force + interpretation as a string. + +# PROGRAMMING INTERFACE + +For the programmer, the SHA1 hash can be viewed as a bucket into which one pours +data. When you have finished, you extract a value that is derived from the data +that was poured into the bucket. The programming interface to the SHA1 hash +operates on a token (equivalent to the bucket). You call __SHA1Init__ to obtain +a token and then call __SHA1Update__ as many times as required to add data to +the hash. To release any resources and obtain the hash value, you then call +__SHA1Final__. An equivalent set of functions gives you a keyed digest (HMAC). + +If you have __critcl__ and have built the __tcllibc__ package then the +implementation of the hashing function will be performed by compiled code. +Failing that if you have the __Trf__ package then this can be used otherwise +there is a pure-tcl equivalent. The programming interface remains the same in +all cases. + + - __::sha1::SHA1Init__ + + Begins a new SHA1 hash. Returns a token ID that must be used for the + remaining functions. + + - __::sha1::SHA1Update__ *token* *data* + + Add data to the hash identified by token. Calling *SHA1Update $token "abcd"* + is equivalent to calling *SHA1Update $token "ab"* followed by *SHA1Update + $token "cb"*. See [EXAMPLES](#section4). + + - __::sha1::SHA1Final__ *token* + + Returns the hash value and releases any resources held by this token. Once + this command completes the token will be invalid. The result is a binary + string of 20 bytes representing the 160 bit SHA1 digest value. + + - __::sha1::HMACInit__ *key* + + This is equivalent to the __::sha1::SHA1Init__ command except that it + requires the key that will be included in the HMAC. + + - __::sha1::HMACUpdate__ *token* *data* + + - __::sha1::HMACFinal__ *token* + + These commands are identical to the SHA1 equivalent commands. + +# EXAMPLES + + % sha1::sha1 "Tcl does SHA1" + 285a6a91c45a9066bf39fcf24425796ef0b2a8bf + + % sha1::hmac Sekret "Tcl does SHA1" + ae6251fa51b95b18cba2be95eb031d07475ff03c + + % set tok [sha1::SHA1Init] + ::sha1::1 + % sha1::SHA1Update $tok "Tcl " + % sha1::SHA1Update $tok "does " + % sha1::SHA1Update $tok "SHA1" + % sha1::Hex [sha1::SHA1Final $tok] + 285a6a91c45a9066bf39fcf24425796ef0b2a8bf + +# REFERENCES + + 1. "Secure Hash Standard", National Institute of Standards and Technology, + U.S. Department Of Commerce, April 1995. + ([http://www.itl.nist.gov/fipspubs/fip180-1.htm](http://www.itl.nist.gov/fipspubs/fip180-1.htm)) + + 1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992. + ([http://www.rfc-editor.org/rfc/rfc1320.txt](http://www.rfc-editor.org/rfc/rfc1320.txt)) + + 1. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message + Authentication", RFC 2104, February 1997. + ([http://www.rfc-editor.org/rfc/rfc2104.txt](http://www.rfc-editor.org/rfc/rfc2104.txt)) + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *sha1* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[md4](../md4/md4.md), [md5](../md5/md5.md), [ripemd128](../ripemd/ripemd128.md), +[ripemd160](../ripemd/ripemd160.md) + +# KEYWORDS + +[FIPS 180-1](../../../../index.md#fips_180_1), +[hashing](../../../../index.md#hashing), +[message-digest](../../../../index.md#message_digest), [rfc +2104](../../../../index.md#rfc_2104), [security](../../../../index.md#security), +[sha1](../../../../index.md#sha1) + +# CATEGORY + +Hashes, checksums, and encryption + +# COPYRIGHT + +Copyright © 2005, Pat Thoyts ADDED embedded/md/tcllib/files/modules/sha1/sha256.md Index: embedded/md/tcllib/files/modules/sha1/sha256.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/sha1/sha256.md @@ -0,0 +1,219 @@ + +[//000000001]: # (sha256 - SHA-x Message-Digest Algorithm) +[//000000002]: # (Generated from file 'sha256.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (sha256(n) 1.0.3 tcllib "SHA-x Message-Digest Algorithm") + +# NAME + +sha256 - SHA256 Message-Digest Algorithm + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [PROGRAMMING INTERFACE](#section3) + + - [EXAMPLES](#section4) + + - [REFERENCES](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require sha256 ?1.0.3? + +[__::sha2::sha256__ ?__-hex|-bin__? [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]](#1) +[__::sha2::sha224__ ?__-hex|-bin__? [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]](#2) +[__::sha2::hmac__ *key* *string*](#3) +[__::sha2::hmac__ ?__-hex|-bin__? __-key key__ [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]](#4) +[__::sha2::SHA256Init__](#5) +[__::sha2::SHA224Init__](#6) +[__::sha2::SHA256Update__ *token* *data*](#7) +[__::sha2::SHA256Final__ *token*](#8) +[__::sha2::SHA224Final__ *token*](#9) +[__::sha2::HMACInit__ *key*](#10) +[__::sha2::HMACUpdate__ *token* *data*](#11) +[__::sha2::HMACFinal__ *token*](#12) + +# DESCRIPTION + +This package provides an implementation in Tcl of the SHA256 and SHA224 +message-digest algorithms as specified by FIPS PUB 180-1 (1). These algorithms +take a message and generates a 256-bit (224-bit) digest from the input. The SHA2 +algorithms are related to the SHA1 algorithm. + +This package also includes support for creating keyed message-digests using the +HMAC algorithm from RFC 2104 (3) with SHA256 as the message-digest. + +# COMMANDS + + - __::sha2::sha256__ ?__-hex|-bin__? [ __-channel channel__ | __-file filename__ | ?__--__? *string* ] + + The command takes a message and returns the SHA256 digest of this message as + a hexadecimal string. You may request the result as binary data by giving + *-bin*. + + The data to be hashed can be specified either as a string argument to the + __sha256__ command, or as a filename or a pre-opened channel. If the + *-filename* argument is given then the file is opened, the data read and + hashed and the file is closed. If the *-channel* argument is given then data + is read from the channel until the end of file. The channel is not closed. + *NOTE* use of the channel or filename options results in the internal use of + __[vwait](../../../../index.md#vwait)__. To avoid nested event loops in Tk + or tclhttpd applications you should use the incremental programming API (see + below). + + Only one of *-file*, *-channel* or *string* should be given. + + If the *string* to hash can be mistaken for an option (leading dash "-"), + use the option __--__ before it to terminate option processing and force + interpretation as a string. + + - __::sha2::sha224__ ?__-hex|-bin__? [ __-channel channel__ | __-file filename__ | ?__--__? *string* ] + + Like __::sha2::sha256__, except that the SHA224 digest is returned. + + - __::sha2::hmac__ *key* *string* + + - __::sha2::hmac__ ?__-hex|-bin__? __-key key__ [ __-channel channel__ | __-file filename__ | ?__--__? *string* ] + + Calculate an Hashed Message Authentication digest (HMAC) using the SHA256 + digest algorithm. HMACs are described in RFC 2104 (3) and provide an SHA256 + digest that includes a key. All options other than *-key* are as for the + __::sha2::sha256__ command. + + If the *string* to hash can be mistaken for an option (leading dash "-"), + use the option __--__ before it to terminate option processing and force + interpretation as a string. + +# PROGRAMMING INTERFACE + +For the programmer, the SHA256 hash can be viewed as a bucket into which one +pours data. When you have finished, you extract a value that is derived from the +data that was poured into the bucket. The programming interface to the SHA256 +hash operates on a token (equivalent to the bucket). You call __SHA256Init__ to +obtain a token and then call __SHA256Update__ as many times as required to add +data to the hash. To release any resources and obtain the hash value, you then +call __SHA256Final__. An equivalent set of functions gives you a keyed digest +(HMAC). + +If you have __critcl__ and have built the __tcllibc__ package then the +implementation of the hashing function will be performed by compiled code. +Failing that there is a pure-tcl equivalent. The programming interface remains +the same in all cases. + + - __::sha2::SHA256Init__ + + - __::sha2::SHA224Init__ + + Begins a new SHA256/SHA224 hash. Returns a token ID that must be used for + the remaining functions. + + - __::sha2::SHA256Update__ *token* *data* + + Add data to the hash identified by token. Calling *SHA256Update $token + "abcd"* is equivalent to calling *SHA256Update $token "ab"* followed by + *SHA256Update $token "cb"*. See [EXAMPLES](#section4). Note that this + command is used for both SHA256 and SHA224. Only the initialization and + finalization commands of both hashes differ. + + - __::sha2::SHA256Final__ *token* + + - __::sha2::SHA224Final__ *token* + + Returns the hash value and releases any resources held by this token. Once + this command completes the token will be invalid. The result is a binary + string of 32/28 bytes representing the 256/224 bit SHA256 / SHA224 digest + value. + + - __::sha2::HMACInit__ *key* + + This is equivalent to the __::sha2::SHA256Init__ command except that it + requires the key that will be included in the HMAC. + + - __::sha2::HMACUpdate__ *token* *data* + + - __::sha2::HMACFinal__ *token* + + These commands are identical to the SHA256 equivalent commands. + +# EXAMPLES + + % sha2::sha256 "Tcl does SHA256" + 0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789 + + % sha2::hmac Sekret "Tcl does SHA256" + 4f9352c64d655e8a36abe73e6163a9d7a54039877c1c92ec90b07d48d4e854e0 + + % set tok [sha2::SHA256Init] + ::sha2::1 + % sha2::SHA256Update $tok "Tcl " + % sha2::SHA256Update $tok "does " + % sha2::SHA256Update $tok "SHA256" + % sha2::Hex [sha2::SHA256Final $tok] + 0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789 + +# REFERENCES + + 1. "Secure Hash Standard", National Institute of Standards and Technology, + U.S. Department Of Commerce, April 1995. + ([http://www.itl.nist.gov/fipspubs/fip180-1.htm](http://www.itl.nist.gov/fipspubs/fip180-1.htm)) + + 1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992. + ([http://www.rfc-editor.org/rfc/rfc1320.txt](http://www.rfc-editor.org/rfc/rfc1320.txt)) + + 1. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message + Authentication", RFC 2104, February 1997. + ([http://www.rfc-editor.org/rfc/rfc2104.txt](http://www.rfc-editor.org/rfc/rfc2104.txt)) + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *sha1* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[md4](../md4/md4.md), [md5](../md5/md5.md), [ripemd128](../ripemd/ripemd128.md), +[ripemd160](../ripemd/ripemd160.md), [sha1](sha1.md) + +# KEYWORDS + +[FIPS 180-1](../../../../index.md#fips_180_1), +[hashing](../../../../index.md#hashing), +[message-digest](../../../../index.md#message_digest), [rfc +2104](../../../../index.md#rfc_2104), [security](../../../../index.md#security), +[sha256](../../../../index.md#sha256) + +# CATEGORY + +Hashes, checksums, and encryption + +# COPYRIGHT + +Copyright © 2008, Andreas Kupries ADDED embedded/md/tcllib/files/modules/simulation/annealing.md Index: embedded/md/tcllib/files/modules/simulation/annealing.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/simulation/annealing.md @@ -0,0 +1,235 @@ + +[//000000001]: # (simulation::annealing - Tcl Simulation Tools) +[//000000002]: # (Generated from file 'annealing.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (simulation::annealing(n) 0.2 tcllib "Tcl Simulation Tools") + +# NAME + +simulation::annealing - Simulated annealing + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [PROCEDURES](#section2) + + - [TIPS](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl ?8.4? +package require simulation::annealing 0.2 + +[__::simulation::annealing::getOption__ *keyword*](#1) +[__::simulation::annealing::hasOption__ *keyword*](#2) +[__::simulation::annealing::setOption__ *keyword* *value*](#3) +[__::simulation::annealing::findMinimum__ *args*](#4) +[__::simulation::annealing::findCombinatorialMinimum__ *args*](#5) + +# DESCRIPTION + +The technique of *simulated annealing* provides methods to estimate the global +optimum of a function. It is described in some detail on the Wiki +[http://wiki.tcl.tk/...](http://wiki.tcl.tk/...). The idea is simple: + + - randomly select points within a given search space + + - evaluate the function to be optimised for each of these points and select + the point that has the lowest (or highest) function value or - sometimes - + accept a point that has a less optimal value. The chance by which such a + non-optimal point is accepted diminishes over time. + + - Accepting less optimal points means the method does not necessarily get + stuck in a local optimum and theoretically it is capable of finding the + global optimum within the search space. + +The method resembles the cooling of material, hence the name. + +The package *simulation::annealing* offers the command *findMinimum*: + + puts [::simulation::annealing::findMinimum -trials 300 -parameters {x -5.0 5.0 y -5.0 5.0} -function {$x*$x+$y*$y+sin(10.0*$x)+4.0*cos(20.0*$y)}] + +prints the estimated minimum value of the function f(x,y) = +*x**2+y**2+sin(10*x)+4*cos(20*y)* and the values of x and y where the minimum +was attained: + + result -4.9112922923 x -0.181647676593 y 0.155743646974 + +# PROCEDURES + +The package defines the following auxiliary procedures: + + - __::simulation::annealing::getOption__ *keyword* + + Get the value of an option given as part of the *findMinimum* command. + + * string *keyword* + + Given keyword (without leading minus) + + - __::simulation::annealing::hasOption__ *keyword* + + Returns 1 if the option is available, 0 if not. + + * string *keyword* + + Given keyword (without leading minus) + + - __::simulation::annealing::setOption__ *keyword* *value* + + Set the value of the given option. + + * string *keyword* + + Given keyword (without leading minus) + + * string *value* + + (New) value for the option + +The main procedures are *findMinimum* and *findCombinatorialMinimum*: + + - __::simulation::annealing::findMinimum__ *args* + + Find the minimum of a function using simulated annealing. The function and + the method's parameters is given via a list of keyword-value pairs. + + * int *n* + + List of keyword-value pairs, all of which are available during the + execution via the *getOption* command. + + - __::simulation::annealing::findCombinatorialMinimum__ *args* + + Find the minimum of a function of discrete variables using simulated + annealing. The function and the method's parameters is given via a list of + keyword-value pairs. + + * int *n* + + List of keyword-value pairs, all of which are available during the + execution via the *getOption* command. + +The *findMinimum* command predefines the following options: + + - *-parameters list*: triples defining parameters and ranges + + - *-function expr*: expression defining the function + + - *-code body*: body of code to define the function (takes precedence over + *-function*). The code should set the variable "result" + + - *-init code*: code to be run at start up *-final code*: code to be run at + the end *-trials n*: number of trials before reducing the temperature + *-reduce factor*: reduce the temperature by this factor (between 0 and 1) + *-initial-temp t*: initial temperature *-scale s*: scale of the function + (order of magnitude of the values) *-estimate-scale y/n*: estimate the scale + (only if *-scale* is not present) *-verbose y/n*: print detailed information + on progress to the report file (1) or not (0) *-reportfile file*: opened + file to print to (defaults to stdout) + +Any other options can be used via the getOption procedure in the body. The +*findCombinatorialMinimum* command predefines the following options: + + - *-number-params n*: number of binary parameters (the solution space consists + of lists of 1s and 0s). This is a required option. + + - *-initial-values*: list of 1s and 0s constituting the start of the search. + +The other predefined options are identical to those of *findMinimum*. + +# TIPS + +The procedure *findMinimum* works by constructing a temporary procedure that +does the actual work. It loops until the point representing the estimated +optimum does not change anymore within the given number of trials. As the +temperature gets lower and lower the chance of accepting a point with a higher +value becomes lower too, so the procedure will in practice terminate. + +It is possible to optimise over a non-rectangular region, but some care must be +taken: + + - If the point is outside the region of interest, you can specify a very high + value. + + - This does mean that the automatic determination of a scale factor is out of + the question - the high function values that force the point inside the + region would distort the estimation. + +Here is an example of finding an optimum inside a circle: + + puts [::simulation::annealing::findMinimum -trials 3000 -reduce 0.98 -parameters {x -5.0 5.0 y -5.0 5.0} -code { + if { hypot($x-5.0,$y-5.0) < 4.0 } { + set result [expr {$x*$x+$y*$y+sin(10.0*$x)+4.0*cos(20.0*$y)}] + } else { + set result 1.0e100 + } + }] + +The method is theoretically capable of determining the global optimum, but often +you need to use a large number of trials and a slow reduction of temperature to +get reliable and repeatable estimates. + +You can use the *-final* option to use a deterministic optimization method, once +you are sure you are near the required optimum. + +The *findCombinatorialMinimum* procedure is suited for situations where the +parameters have the values 0 or 1 (and there can be many of them). Here is an +example: + + - We have a function that attains an absolute minimum if the first ten numbers + are 1 and the rest is 0: + + proc cost {params} { + set cost 0 + foreach p [lrange $params 0 9] { + if { $p == 0 } { + incr cost + } + } + foreach p [lrange $params 10 end] { + if { $p == 1 } { + incr cost + } + } + return $cost + } + + - We want to find the solution that gives this minimum for various lengths of + the solution vector *params*: + + foreach n {100 1000 10000} { + break + puts "Problem size: $n" + puts [::simulation::annealing::findCombinatorialMinimum -trials 300 -verbose 0 -number-params $n -code {set result [cost $params]}] + } + + - As the vector grows, the computation time increases, but the procedure will + stop if some kind of equilibrium is reached. To achieve a useful solution + you may want to try different values of the trials parameter for instance. + Also ensure that the function to be minimized depends on all or most + parameters - see the source code for a counter example and run that. + +# KEYWORDS + +[math](../../../../index.md#math), +[optimization](../../../../index.md#optimization), [simulated +annealing](../../../../index.md#simulated_annealing) + +# CATEGORY + +Mathematics + +# COPYRIGHT + +Copyright © 2008 Arjen Markus ADDED embedded/md/tcllib/files/modules/simulation/montecarlo.md Index: embedded/md/tcllib/files/modules/simulation/montecarlo.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/simulation/montecarlo.md @@ -0,0 +1,231 @@ + +[//000000001]: # (simulation::montecarlo - Tcl Simulation Tools) +[//000000002]: # (Generated from file 'montecarlo.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (simulation::montecarlo(n) 0.1 tcllib "Tcl Simulation Tools") + +# NAME + +simulation::montecarlo - Monte Carlo simulations + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [PROCEDURES](#section2) + + - [TIPS](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl ?8.4? +package require simulation::montecarlo 0.1 +package require simulation::random +package require math::statistics + +[__::simulation::montecarlo::getOption__ *keyword*](#1) +[__::simulation::montecarlo::hasOption__ *keyword*](#2) +[__::simulation::montecarlo::setOption__ *keyword* *value*](#3) +[__::simulation::montecarlo::setTrialResult__ *values*](#4) +[__::simulation::montecarlo::setExpResult__ *values*](#5) +[__::simulation::montecarlo::getTrialResults__](#6) +[__::simulation::montecarlo::getExpResult__](#7) +[__::simulation::montecarlo::transposeData__ *values*](#8) +[__::simulation::montecarlo::integral2D__ *...*](#9) +[__::simulation::montecarlo::singleExperiment__ *args*](#10) + +# DESCRIPTION + +The technique of *Monte Carlo simulations* is basically simple: + + - generate random values for one or more parameters. + + - evaluate the model of some system you are interested in and record the + interesting results for each realisation of these parameters. + + - after a suitable number of such trials, deduce an overall characteristic of + the model. + +You can think of a model of a network of computers, an ecosystem of some kind or +in fact anything that can be quantitatively described and has some stochastic +element in it. + +The package *simulation::montecarlo* offers a basic framework for such a +modelling technique: + + # + # MC experiments: + # Determine the mean and median of a set of points and compare them + # + ::simulation::montecarlo::singleExperiment -init { + package require math::statistics + + set prng [::simulation::random::prng_Normal 0.0 1.0] + } -loop { + set numbers {} + for { set i 0 } { $i < [getOption samples] } { incr i } { + lappend numbers [$prng] + } + set mean [::math::statistics::mean $numbers] + set median [::math::statistics::median $numbers] ;# ? Exists? + setTrialResult [list $mean $median] + } -final { + set result [getTrialResults] + set means {} + set medians {} + foreach r $result { + foreach {m M} $r break + lappend means $m + lappend medians $M + } + puts [getOption reportfile] "Correlation: [::math::statistics::corr $means $medians]" + + } -trials 100 -samples 10 -verbose 1 -columns {Mean Median} + +This example attemps to find out how well the median value and the mean value of +a random set of numbers correlate. Sometimes a median value is a more robust +characteristic than a mean value - especially if you have a statistical +distribution with "fat" tails. + +# PROCEDURES + +The package defines the following auxiliary procedures: + + - __::simulation::montecarlo::getOption__ *keyword* + + Get the value of an option given as part of the *singeExperiment* command. + + * string *keyword* + + Given keyword (without leading minus) + + - __::simulation::montecarlo::hasOption__ *keyword* + + Returns 1 if the option is available, 0 if not. + + * string *keyword* + + Given keyword (without leading minus) + + - __::simulation::montecarlo::setOption__ *keyword* *value* + + Set the value of the given option. + + * string *keyword* + + Given keyword (without leading minus) + + * string *value* + + (New) value for the option + + - __::simulation::montecarlo::setTrialResult__ *values* + + Store the results of the trial for later analysis + + * list *values* + + List of values to be stored + + - __::simulation::montecarlo::setExpResult__ *values* + + Set the results of the entire experiment (typically used in the final + phase). + + * list *values* + + List of values to be stored + + - __::simulation::montecarlo::getTrialResults__ + + Get the results of all individual trials for analysis (typically used in the + final phase or after completion of the command). + + - __::simulation::montecarlo::getExpResult__ + + Get the results of the entire experiment (typically used in the final phase + or even after completion of the *singleExperiment* command). + + - __::simulation::montecarlo::transposeData__ *values* + + Interchange columns and rows of a list of lists and return the result. + + * list *values* + + List of lists of values + +There are two main procedures: *integral2D* and *singleExperiment*. + + - __::simulation::montecarlo::integral2D__ *...* + + Integrate a function over a two-dimensional region using a Monte Carlo + approach. + + Arguments PM + + - __::simulation::montecarlo::singleExperiment__ *args* + + Iterate code over a number of trials and store the results. The iteration is + gouverned by parameters given via a list of keyword-value pairs. + + * int *n* + + List of keyword-value pairs, all of which are available during the + execution via the *getOption* command. + +The *singleExperiment* command predefines the following options: + + - *-init code*: code to be run at start up + + - *-loop body*: body of code that defines the computation to be run time and + again. The code should use *setTrialResult* to store the results of each + trial (typically a list of numbers, but the interpretation is up to the + implementation). Note: Required keyword. + + - *-final code*: code to be run at the end + + - *-trials n*: number of trials in the experiment (required) + + - *-reportfile file*: opened file to send the output to (default: stdout) + + - *-verbose*: write the intermediate results (1) or not (0) (default: 0) + + - *-analysis proc*: either "none" (no automatic analysis), standard (basic + statistics of the trial results and a correlation matrix) or the name of a + procedure that will take care of the analysis. + + - *-columns list*: list of column names, useful for verbose output and the + analysis + +Any other options can be used via the getOption procedure in the body. + +# TIPS + +The procedure *singleExperiment* works by constructing a temporary procedure +that does the actual work. It loops for the given number of trials. + +As it constructs a temporary procedure, local variables defined at the start +continue to exist in the loop. + +# KEYWORDS + +[math](../../../../index.md#math), [montecarlo +simulation](../../../../index.md#montecarlo_simulation), [stochastic +modelling](../../../../index.md#stochastic_modelling) + +# CATEGORY + +Mathematics + +# COPYRIGHT + +Copyright © 2008 Arjen Markus ADDED embedded/md/tcllib/files/modules/simulation/simulation_random.md Index: embedded/md/tcllib/files/modules/simulation/simulation_random.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/simulation/simulation_random.md @@ -0,0 +1,249 @@ + +[//000000001]: # (simulation::random - Tcl Simulation Tools) +[//000000002]: # (Generated from file 'simulation_random.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (simulation::random(n) 0.1 tcllib "Tcl Simulation Tools") + +# NAME + +simulation::random - Pseudo-random number generators + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [PROCEDURES](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl ?8.4? +package require simulation::random 0.1 + +[__::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) + +# DESCRIPTION + +This package consists of commands to generate pseudo-random number generators. +These new commands deliver + + - numbers that are distributed normally, uniformly, according to a Pareto or + Gumbel distribution and so on + + - coordinates of points uniformly spread inside a sphere or a rectangle + +For example: + + set p [::simulation::random::prng_Normal -1.0 10.0] + +produces a new command (whose name is stored in the variable "p") that generates +normally distributed numbers with a mean of -1.0 and a standard deviation of +10.0. + +# PROCEDURES + +The package defines the following public procedures for *discrete* +distributions: + + - __::simulation::random::prng_Bernoulli__ *p* + + Create a command (PRNG) that generates numbers with a Bernoulli + distribution: the value is either 1 or 0, with a chance p to be 1 + + * float *p* + + Chance the outcome is 1 + + - __::simulation::random::prng_Discrete__ *n* + + Create a command (PRNG) that generates numbers 0 to n-1 with equal + probability. + + * int *n* + + Number of different values (ranging from 0 to n-1) + + - __::simulation::random::prng_Poisson__ *lambda* + + Create a command (PRNG) that generates numbers according to the Poisson + distribution. + + * float *lambda* + + Mean number per time interval + +The package defines the following public procedures for *continuous* +distributions: + + - __::simulation::random::prng_Uniform__ *min* *max* + + Create a command (PRNG) that generates uniformly distributed numbers between + "min" and "max". + + * float *min* + + Minimum number that will be generated + + * float *max* + + Maximum number that will be generated + + - __::simulation::random::prng_Exponential__ *min* *mean* + + Create a command (PRNG) that generates exponentially distributed numbers + with a given minimum value and a given mean value. + + * float *min* + + Minimum number that will be generated + + * float *mean* + + Mean value for the numbers + + - __::simulation::random::prng_Normal__ *mean* *stdev* + + Create a command (PRNG) that generates normally distributed numbers with a + given mean value and a given standard deviation. + + * float *mean* + + Mean value for the numbers + + * float *stdev* + + Standard deviation + + - __::simulation::random::prng_Pareto__ *min* *steep* + + Create a command (PRNG) that generates numbers distributed according to + Pareto with a given minimum value and a given distribution steepness. + + * float *min* + + Minimum number that will be generated + + * float *steep* + + Steepness of the distribution + + - __::simulation::random::prng_Gumbel__ *min* *f* + + Create a command (PRNG) that generates numbers distributed according to + Gumbel with a given minimum value and a given scale factor. The probability + density function is: + + P(v) = exp( -exp(f*(v-min))) + + * float *min* + + Minimum number that will be generated + + * float *f* + + Scale factor for the values + + - __::simulation::random::prng_chiSquared__ *df* + + Create a command (PRNG) that generates numbers distributed according to the + chi-squared distribution with df degrees of freedom. The mean is 0 and the + standard deviation is 1. + + * float *df* + + Degrees of freedom + +The package defines the following public procedures for random point sets: + + - __::simulation::random::prng_Disk__ *rad* + + Create a command (PRNG) that generates (x,y)-coordinates for points + uniformly spread over a disk of given radius. + + * float *rad* + + Radius of the disk + + - __::simulation::random::prng_Sphere__ *rad* + + Create a command (PRNG) that generates (x,y,z)-coordinates for points + uniformly spread over the surface of a sphere of given radius. + + * float *rad* + + Radius of the disk + + - __::simulation::random::prng_Ball__ *rad* + + Create a command (PRNG) that generates (x,y,z)-coordinates for points + uniformly spread within a ball of given radius. + + * float *rad* + + Radius of the ball + + - __::simulation::random::prng_Rectangle__ *length* *width* + + Create a command (PRNG) that generates (x,y)-coordinates for points + uniformly spread over a rectangle. + + * float *length* + + Length of the rectangle (x-direction) + + * float *width* + + Width of the rectangle (y-direction) + + - __::simulation::random::prng_Block__ *length* *width* *depth* + + Create a command (PRNG) that generates (x,y,z)-coordinates for points + uniformly spread over a block + + * float *length* + + Length of the block (x-direction) + + * float *width* + + Width of the block (y-direction) + + * float *depth* + + Depth of the block (z-direction) + +# KEYWORDS + +[math](../../../../index.md#math), [random +numbers](../../../../index.md#random_numbers), +[simulation](../../../../index.md#simulation), [statistical +distribution](../../../../index.md#statistical_distribution) + +# CATEGORY + +Mathematics + +# COPYRIGHT + +Copyright © 2004 Arjen Markus ADDED embedded/md/tcllib/files/modules/smtpd/smtpd.md Index: embedded/md/tcllib/files/modules/smtpd/smtpd.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/smtpd/smtpd.md @@ -0,0 +1,311 @@ + +[//000000001]: # (smtpd - Tcl SMTP Server Package) +[//000000002]: # (Generated from file 'smtpd.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (smtpd(n) 1.5 tcllib "Tcl SMTP Server Package") + +# NAME + +smtpd - Tcl SMTP server implementation + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [SECURITY](#section2) + + - [TLS Security Considerations](#section3) + + - [COMMANDS](#section4) + + - [CALLBACKS](#section5) + + - [VARIABLES](#section6) + + - [AUTHOR](#section7) + + - [LICENSE](#section8) + + - [Bugs, Ideas, Feedback](#section9) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.3 +package require smtpd ?1.5? + +[__::smtpd::start__ ?*myaddr*? ?*port*?](#1) +[__::smtpd::stop__](#2) +[__::smptd::configure__ ?*option* *value*? ?*option* *value* *...*?](#3) +[__::smtpd::cget__ ?*option*?](#4) + +# DESCRIPTION + +The __smtpd__ package provides a simple Tcl-only server library for the Simple +Mail Transfer Protocol as described in RFC 821 +([http://www.rfc-editor.org/rfc/rfc821.txt](http://www.rfc-editor.org/rfc/rfc821.txt)) +and RFC 2821 +([http://www.rfc-editor.org/rfc/rfc2821.txt](http://www.rfc-editor.org/rfc/rfc2821.txt)). +By default the server will bind to the default network address and the standard +SMTP port (25). + +This package was designed to permit testing of Mail User Agent code from a +developers workstation. *It does not attempt to deliver mail to your mailbox.* +Instead users of this package are expected to write a procedure that will be +called when mail arrives. Once this procedure returns, the server has nothing +further to do with the mail. + +# SECURITY + +On Unix platforms binding to the SMTP port requires root privileges. I would not +recommend running any script-based server as root unless there is some method +for dropping root privileges immediately after the socket is bound. Under +Windows platforms, it is not necessary to have root or administrator privileges +to bind low numbered sockets. However, security on these platforms is weak +anyway. + +In short, this code should probably not be used as a permanently running Mail +Transfer Agent on an Internet connected server, even though we are careful not +to evaluate remote user input. There are many other well tested and security +audited programs that can be used as mail servers for internet connected hosts. + +# TLS Security Considerations + +This package uses the __[TLS](../../../../index.md#tls)__ package to handle the +security for __https__ urls and other socket connections. + +Policy decisions like the set of protocols to support and what ciphers to use +are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this +package itself however. Such decisions are the responsibility of whichever +application is using the package, and are likely influenced by the set of +servers the application will talk to as well. + +For example, in light of the recent [POODLE +attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html) +discovered by Google many servers will disable support for the SSLv3 protocol. +To handle this change the applications using __[TLS](../../../../index.md#tls)__ +must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__ +itself. Such a patch may be as simple as generally activating __tls1__ support, +as shown in the example below. + + package require tls + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol + + ... your own application code ... + +# COMMANDS + + - __::smtpd::start__ ?*myaddr*? ?*port*? + + Start the service listening on *port* or the default port 25. If *myaddr* is + given as a domain-style name or numerical dotted-quad IP address then the + server socket will be bound to that network interface. By default the server + is bound to all network interfaces. For example: + + set sock [::smtpd::start [info hostname] 0] + + will bind to the hosts internet interface on the first available port. + + At present the package only supports a single instance of a SMTP server. + This could be changed if required at the cost of making the package a little + more complicated to read. If there is a good reason for running multiple + SMTP services then it will only be necessary to fix the __options__ array + and the __::smtpd::stopped__ variable usage. + + As the server code uses __fileevent__(n) handlers to process the input on + sockets you will need to run the event loop. This means either you should be + running from within __wish__(1) or you should + __[vwait](../../../../index.md#vwait)__(n) on the __::smtpd::stopped__ + variable which is set when the server is stopped. + + - __::smtpd::stop__ + + Halt the server and release the listening socket. If the server has not been + started then this command does nothing. The __::smtpd::stopped__ variable is + set for use with __[vwait](../../../../index.md#vwait)__(n). + + It should be noted that stopping the server does not disconnect any + currently active sessions as these are operating over an independent + channel. Only explicitly tracking and closing these sessions, or exiting the + server process will close down all the running sessions. This is similar to + the usual unix daemon practice where the server performs a __fork__(2) and + the client session continues on the child process. + + - __::smptd::configure__ ?*option* *value*? ?*option* *value* *...*? + + Set configuration options for the SMTP server. Most values are the name of a + callback procedure to be called at various points in the SMTP protocol. See + the [CALLBACKS](#section5) section for details of the procedures. + + * __-banner__ *text* + + Text of a custom banner message. The default banner is "tcllib smtpd + 1.5". Note that changing the banner does not affect the bracketing text + in the full greeting, printing status 220, server-address, and + timestamp. + + * __-validate_host__ *proc* + + Callback to authenticate new connections based on the ip-address of the + client. + + * __-validate_sender__ *proc* + + Callback to authenticate new connections based on the senders email + address. + + * __-validate_recipient__ *proc* + + Callback to validate and authorize a recipient email address + + * __-deliverMIME__ *proc* + + Callback used to deliver mail as a mime token created by the tcllib + __[mime](../mime/mime.md)__ package. + + * __-deliver__ *proc* + + Callback used to deliver email. This option has no effect if the + __-deliverMIME__ option has been set. + + - __::smtpd::cget__ ?*option*? + + If no *option* is specified the command will return a list of all options + and their current values. If an option is specified it will return the value + of that option. + +# CALLBACKS + + - __validate_host__ callback + + This procedure is called with the clients ip address as soon as a connection + request has been accepted and before any protocol commands are processed. If + you wish to deny access to a specific host then an error should be returned + by this callback. For example: + + proc validate_host {ipnum} { + if {[string match "192.168.1.*" $ipnum]} { + error "go away!" + } + } + + If access is denied the client will receive a standard message that includes + the text of your error, such as: + + 550 Access denied: I hate you. + + As per the SMTP protocol, the connection is not closed but we wait for the + client to send a QUIT command. Any other commands cause a __503 Bad + Sequence__ error. + + - __validate_sender__ callback + + The validate_sender callback is called with the senders mail address during + processing of a MAIL command to allow you to accept or reject mail based + upon the declared sender. To reject mail you should throw an error. For + example, to reject mail from user "denied": + + proc validate_sender {address} { + eval array set addr [mime::parseaddress $address] + if {[string match "denied" $addr(local)]} { + error "mailbox $addr(local) denied" + } + return + } + + The content of any error message will not be passed back to the client. + + - __validate_recipient__ callback + + The validate_recipient callback is similar to the validate_sender callback + and permits you to verify a local mailbox and accept mail for a local user + address during RCPT command handling. To reject mail, throw an error as + above. The error message is ignored. + + - __deliverMIME__ callback + + The deliverMIME callback is called once a mail message has been successfully + passed to the server. A mime token is constructed from the sender, + recipients and data and the users procedure it called with this single + argument. When the call returns, the mime token is cleaned up so if the user + wishes to preserve the data she must make a copy. + + proc deliverMIME {token} { + set sender [lindex [mime::getheader $token From] 0] + set recipients [lindex [mime::getheader $token To] 0] + set mail "From $sender [clock format [clock seconds]]" + append mail "\n" [mime::buildmessage $token] + puts $mail + } + + - __deliver__ callback + + The deliver callback is called once a mail message has been successfully + passed to the server and there is no -deliverMIME option set. The procedure + is called with the sender, a list of recipients and the text of the mail as + a list of lines. For example: + + proc deliver {sender recipients data} { + set mail "From $sender [clock format [clock seconds]]" + append mail "\n" [join $data "\n"] + puts "$mail" + } + + Note that the DATA command will return an error if no sender or recipient + has yet been defined. + +# VARIABLES + + - __::smtpd::stopped__ + + This variable is set to __true__ during the __::smtpd::stop__ command to + permit the use of the __[vwait](../../../../index.md#vwait)__(n) command. + +# AUTHOR + +Written by Pat Thoyts +[mailto:patthoyts@users.sourceforge.net](mailto:patthoyts@users.sourceforge.net). + +# LICENSE + +This software is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. See the file "license.terms" for more details. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *smtpd* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[rfc 2821](../../../../index.md#rfc_2821), [rfc +821](../../../../index.md#rfc_821), [services](../../../../index.md#services), +[smtp](../../../../index.md#smtp), [smtpd](../../../../index.md#smtpd), +[socket](../../../../index.md#socket), [vwait](../../../../index.md#vwait) + +# CATEGORY + +Networking + +# COPYRIGHT + +Copyright © Pat Thoyts ADDED embedded/md/tcllib/files/modules/snit/snit.md Index: embedded/md/tcllib/files/modules/snit/snit.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/snit/snit.md @@ -0,0 +1,2355 @@ + +[//000000001]: # (snit - Snit's Not Incr Tcl, OO system) +[//000000002]: # (Generated from file 'snit.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (snit(n) 2.3.2 tcllib "Snit's Not Incr Tcl, OO system") + +# NAME + +snit - Snit's Not Incr Tcl + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [SNIT VERSIONS](#section2) + + - [REFERENCE](#section3) + + - [Type and Widget Definitions](#subsection1) + + - [The Type Command](#subsection2) + + - [Standard Type Methods](#subsection3) + + - [The Instance Command](#subsection4) + + - [Standard Instance Methods](#subsection5) + + - [Commands for use in Object Code](#subsection6) + + - [Components and Delegation](#subsection7) + + - [Type Components and Delegation](#subsection8) + + - [The Tk Option Database](#subsection9) + + - [Macros and Meta-programming](#subsection10) + + - [Validation Types](#subsection11) + + - [Defining Validation Types](#subsection12) + + - [CAVEATS](#section4) + + - [KNOWN BUGS](#section5) + + - [HISTORY](#section6) + + - [CREDITS](#section7) + + - [Bugs, Ideas, Feedback](#section8) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit ?2.3.2? + +[__snit::type__ *name* *definition*](#1) +[__typevariable__ *name* ?__-array__? ?*value*?](#2) +[__typemethod__ *name* *arglist* *body*](#3) +[__typeconstructor__ *body*](#4) +[__variable__ *name* ?__-array__? ?*value*?](#5) +[__[method](../../../../index.md#method)__ *name* *arglist* *body*](#6) +[__option__ *namespec* ?*defaultValue*?](#7) +[__option__ *namespec* ?*options...*?](#8) +[__constructor__ *arglist* *body*](#9) +[__destructor__ *body*](#10) +[__[proc](../../../../index.md#proc)__ *name* *args* *body*](#11) +[__delegate__ __method__ *name* __to__ *comp* ?__as__ *target*?](#12) +[__delegate__ __method__ *name* ?__to__ *comp*? __using__ *pattern*](#13) +[__delegate__ __method__ __*__ ?__to__ *comp*? ?__using__ *pattern*? ?__except__ *exceptions*?](#14) +[__delegate__ __option__ *namespec* __to__ *comp*](#15) +[__delegate__ __option__ *namespec* __to__ *comp* __as__ *target*](#16) +[__delegate__ __option__ __*__ __to__ *comp*](#17) +[__delegate__ __option__ __*__ __to__ *comp* __except__ *exceptions*](#18) +[__component__ *comp* ?__-public__ *method*? ?__-inherit__ *flag*?](#19) +[__delegate__ __typemethod__ *name* __to__ *comp* ?__as__ *target*?](#20) +[__delegate__ __typemethod__ *name* ?__to__ *comp*? __using__ *pattern*](#21) +[__delegate__ __typemethod__ __*__ ?__to__ *comp*? ?__using__ *pattern*? ?__except__ *exceptions*?](#22) +[__typecomponent__ *comp* ?__-public__ *typemethod*? ?__-inherit__ *flag*?](#23) +[__pragma__ ?*options...*?](#24) +[__expose__ *comp*](#25) +[__expose__ *comp* __as__ *method*](#26) +[__onconfigure__ *name* *arglist* *body*](#27) +[__oncget__ *name* *body*](#28) +[__snit::widget__ *name* *definition*](#29) +[__widgetclass__ *name*](#30) +[__hulltype__ *type*](#31) +[__snit::widgetadaptor__ *name* *definition*](#32) +[__snit::typemethod__ *type* *name* *arglist* *body*](#33) +[__snit::method__ *type* *name* *arglist* *body*](#34) +[__snit::macro__ *name* *arglist* *body*](#35) +[__snit::compile__ *which* *type* *body*](#36) +[__$type__ *typemethod* *args*...](#37) +[__$type__ __create__ *name* ?*option* *value* ...?](#38) +[__$type__ __info typevars__ ?*pattern*?](#39) +[__$type__ __info typemethods__ ?*pattern*?](#40) +[__$type__ __info args__ *method*](#41) +[__$type__ __info body__ *method*](#42) +[__$type__ __info default__ *method* *aname* *varname*](#43) +[__$type__ __info instances__ ?*pattern*?](#44) +[__$type__ __destroy__](#45) +[__$object__ *method* *args...*](#46) +[__$object__ __configure__ ?*option*? ?*value*? ...](#47) +[__$object__ __configurelist__ *optionlist*](#48) +[__$object__ __cget__ *option*](#49) +[__$object__ __destroy__](#50) +[__$object__ __info type__](#51) +[__$object__ __info vars__ ?*pattern*?](#52) +[__$object__ __info typevars__ ?*pattern*?](#53) +[__$object__ __info typemethods__ ?*pattern*?](#54) +[__$object__ __info options__ ?*pattern*?](#55) +[__$object__ __info methods__ ?*pattern*?](#56) +[__$object__ __info args__ *method*](#57) +[__$object__ __info body__ *method*](#58) +[__$object__ __info default__ *method* *aname* *varname*](#59) +[__mymethod__ *name* ?*args...*?](#60) +[__mytypemethod__ *name* ?*args...*?](#61) +[__myproc__ *name* ?*args...*?](#62) +[__myvar__ *name*](#63) +[__mytypevar__ *name*](#64) +[__from__ *argvName* *option* ?*defvalue*?](#65) +[__install__ *compName* __using__ *objType* *objName* *args...*](#66) +[__installhull__ __using__ *widgetType* *args...*](#67) +[__installhull__ *name*](#68) +[__variable__ *name*](#69) +[__typevariable__ *name*](#70) +[__varname__ *name*](#71) +[__typevarname__ *name*](#72) +[__codename__ *name*](#73) +[__snit::boolean__ __validate__ ?*value*?](#74) +[__snit::boolean__ *name*](#75) +[__snit::double__ __validate__ ?*value*?](#76) +[__snit::double__ *name* ?*option* *value*...?](#77) +[__snit::enum__ __validate__ ?*value*?](#78) +[__snit::enum__ *name* ?*option* *value*...?](#79) +[__snit::fpixels__ __validate__ ?*value*?](#80) +[__snit::fpixels__ *name* ?*option* *value*...?](#81) +[__snit::integer__ __validate__ ?*value*?](#82) +[__snit::integer__ *name* ?*option* *value*...?](#83) +[__snit::listtype__ __validate__ ?*value*?](#84) +[__snit::listtype__ *name* ?*option* *value*...?](#85) +[__snit::pixels__ __validate__ ?*value*?](#86) +[__snit::pixels__ *name* ?*option* *value*...?](#87) +[__snit::stringtype__ __validate__ ?*value*?](#88) +[__snit::stringtype__ *name* ?*option* *value*...?](#89) +[__snit::window__ __validate__ ?*value*?](#90) +[__snit::window__ *name*](#91) + +# DESCRIPTION + +Snit is a pure Tcl object and megawidget system. It's unique among Tcl object +systems in that it's based not on inheritance but on delegation. Object systems +based on inheritance only allow you to inherit from classes defined using the +same system, which is limiting. In Tcl, an object is anything that acts like an +object; it shouldn't matter how the object was implemented. Snit is intended to +help you build applications out of the materials at hand; thus, Snit is designed +to be able to incorporate and build on any object, whether it's a hand-coded +object, a __[Tk](../../../../index.md#tk)__ widget, an __[Incr +Tcl](../../../../index.md#incr_tcl)__ object, a +__[BWidget](../../../../index.md#bwidget)__ or almost anything else. + +This man page is intended to be a reference only; see the accompanying +__[snitfaq](snitfaq.md)__ for a gentler, more tutorial introduction to Snit +concepts. + +# SNIT VERSIONS + +This man page covers both Snit 2.2 and Snit 1.3. The primary difference between +the two versions is simply that Snit 2.2 contains speed optimizations based on +new features of Tcl 8.5; Snit 1.3 supports all of Tcl 8.3, 8.4 and Tcl 8.5. +There are a few minor inconsistencies; they are flagged in the body of the man +page with the label "Snit 1.x Incompatibility"; they are also discussed in the +__[snitfaq](snitfaq.md)__. + +# REFERENCE + +## Type and Widget Definitions + +Snit provides the following commands for defining new types: + + - __snit::type__ *name* *definition* + + Defines a new abstract data type called *name*. If *name* is not a fully + qualified command name, it is assumed to be a name in the namespace in which + the __snit::type__ command was called (usually the global namespace). It + returns the fully qualified name of the new type. + + The type name is then a command that is used to create objects of the new + type, along with other activities. + + The __snit::type__ *definition* block is a script that may contain the + following definitions: + + * __typevariable__ *name* ?__-array__? ?*value*? + + Defines a type variable with the specified *name*, and optionally the + specified *value*. Type variables are shared by all instances of the + type. If the __-array__ option is included, then *value* should be a + dictionary; it will be assigned to the variable using __array set__. + + * __typemethod__ *name* *arglist* *body* + + Defines a type method, a subcommand of the new type command, with the + specified name, argument list, and body. The *arglist* is a normal Tcl + argument list and may contain default arguments and the __args__ + argument; however, it may not contain the argument names __type__, + __self__, __selfns__, or __win__. + + The variable __type__ is automatically defined in the *body* to the + type's fully-qualified name. In addition, type variables are + automatically visible in the *body* of every type method. + + If the *name* consists of two or more tokens, Snit handles it specially: + + typemethod {a b} {arg} { puts "Got $arg" } + + This statement implicitly defines a type method called __a__ which has a + subcommand __b__. __b__ is called like this: + + $type a b "Hello, world!" + + __a__ may have any number of subcommands. This makes it possible to + define a hierarchical command structure; see + __[method](../../../../index.md#method)__, below, for more examples. + + Type methods can call commands from the namespace in which the type is + defined without importing them, e.g., if the type name is + __::parentns::typename__, then the type's type methods can call + __::parentns::someproc__ just as __someproc__. *Snit 1.x + Incompatibility:* This does not work in Snit 1.x, as it depends on + __namespace path__, a new command in Tcl 8.5. + + *Snit 1.x Incompatibility:* In Snit 1.x, the following following two + calls to this type method are equivalent: + + $type a b "Hello, world!" + $type {a b} "Hello, world!" + + In Snit 2.2, the second form is invalid. + + * __typeconstructor__ *body* + + The type constructor's *body* is executed once when the type is first + defined; it is typically used to initialize array-valued type variables + and to add entries to [The Tk Option Database](#subsection9). + + The variable __type__ is automatically defined in the *body*, and + contains the type's fully-qualified name. In addition, type variables + are automatically visible in the *body* of the type constructor. + + A type may define at most one type constructor. + + The type constructor can call commands from the namespace in which the + type is defined without importing them, e.g., if the type name is + __::parentns::typename__, then the type constructor can call + __::parentns::someproc__ just as __someproc__. *Snit 1.x + Incompatibility:* This does not work in Snit 1.x, as it depends on + __namespace path__, a new command in Tcl 8.5. + + * __variable__ *name* ?__-array__? ?*value*? + + Defines an instance variable, a private variable associated with each + instance of this type, and optionally its initial value. If the + __-array__ option is included, then *value* should be a dictionary; it + will be assigned to the variable using __array set__. + + * __[method](../../../../index.md#method)__ *name* *arglist* *body* + + Defines an instance method, a subcommand of each instance of this type, + with the specified name, argument list and body. The *arglist* is a + normal Tcl argument list and may contain default arguments and the + __args__ argument. + + The method is implicitly passed the following arguments as well: + __type__, which contains the fully-qualified type name; __self__, which + contains the current instance command name; __selfns__, which contains + the name of the instance's private namespace; and __win__, which + contains the original instance name. Consequently, the *arglist* may not + contain the argument names __type__, __self__, __selfns__, or __win__. + + An instance method defined in this way is said to be *locally defined*. + + Type and instance variables are automatically visible in all instance + methods. If the type has locally defined options, the __options__ array + is also visible. + + If the *name* consists of two or more tokens, Snit handles it specially: + + method {a b} {} { ... } + + This statement implicitly defines a method called __a__ which has a + subcommand __b__. __b__ is called like this: + + $self a b "Hello, world!" + + __a__ may have any number of subcommands. This makes it possible to + define a hierarchical command structure: + + % snit::type dog { + method {tail wag} {} {return "Wag, wag"} + method {tail droop} {} {return "Droop, droop"} + } + ::dog + % dog spot + ::spot + % spot tail wag + Wag, wag + % spot tail droop + Droop, droop + % + + What we've done is implicitly defined a "tail" method with subcommands + "wag" and "droop". Consequently, it's an error to define "tail" + explicitly. + + Methods can call commands from the namespace in which the type is + defined without importing them, e.g., if the type name is + __::parentns::typename__, then the type's methods can call + __::parentns::someproc__ just as __someproc__. *Snit 1.x + Incompatibility:* This does not work in Snit 1.x, as it depends on + __namespace path__, a new command in Tcl 8.5. + + *Snit 1.x Incompatibility:* In Snit 1.x, the following following two + calls to this method are equivalent: + + $self a b "Hello, world!" + $self {a b} "Hello, world!" + + In Snit 2.2, the second form is invalid. + + * __option__ *namespec* ?*defaultValue*? + + * __option__ *namespec* ?*options...*? + + Defines an option for instances of this type, and optionally gives it an + initial value. The initial value defaults to the empty string if no + *defaultValue* is specified. + + An option defined in this way is said to be *locally defined*. + + The *namespec* is a list defining the option's name, resource name, and + class name, e.g.: + + option {-font font Font} {Courier 12} + + The option name must begin with a hyphen, and must not contain any upper + case letters. The resource name and class name are optional; if not + specified, the resource name defaults to the option name, minus the + hyphen, and the class name defaults to the resource name with the first + letter capitalized. Thus, the following statement is equivalent to the + previous example: + + option -font {Courier 12} + + See [The Tk Option Database](#subsection9) for more information about + resource and class names. + + Options are normally set and retrieved using the standard instance + methods __configure__ and __cget__; within instance code (method bodies, + etc.), option values are available through the __options__ array: + + set myfont $options(-font) + + If the type defines any option handlers (e.g., __-configuremethod__), + then it should probably use __configure__ and __cget__ to access its + options to avoid subtle errors. + + The __option__ statement may include the following options: + + + __-default__ *defvalue* + + Defines the option's default value; the option's default value will + be "" otherwise. + + + __-readonly__ *flag* + + The *flag* can be any Boolean value recognized by Tcl. If *flag* is + true, then the option is read-only--it can only be set using + __configure__ or __configurelist__ at creation time, i.e., in the + type's constructor. + + + __-type__ *type* + + Every locally-defined option may define its validation type, which + may be either the name of a validation type or a specification for a + validation subtype + + For example, an option may declare that its value must be an integer + by specifying __snit::integer__ as its validation type: + + option -number -type snit::integer + + It may also declare that its value is an integer between 1 and 10 by + specifying a validation subtype: + + option -number -type {snit::integer -min 1 -max 10} + + If a validation type or subtype is defined for an option, then it + will be used to validate the option's value whenever it is changed + by the object's __configure__ or __configurelist__ methods. In + addition, all such options will have their values validated + automatically immediately after the constructor executes. + + Snit defines a family of validation types and subtypes, and it's + quite simple to define new ones. See [Validation + Types](#subsection11) for the complete list, and [Defining + Validation Types](#subsection12) for an explanation of how to define + your own. + + + __-cgetmethod__ *methodName* + + Every locally-defined option may define a __-cgetmethod__; it is + called when the option's value is retrieved using the __cget__ + method. Whatever the method's *body* returns will be the return + value of the call to __cget__. + + The named method must take one argument, the option name. For + example, this code is equivalent to (though slower than) Snit's + default handling of __cget__: + + option -font -cgetmethod GetOption + method GetOption {option} { + return $options($option) + } + + Note that it's possible for any number of options to share a + __-cgetmethod__. + + + __-configuremethod__ *methodName* + + Every locally-defined option may define a __-configuremethod__; it + is called when the option's value is set using the __configure__ or + __configurelist__ methods. It is the named method's responsibility + to save the option's value; in other words, the value will not be + saved to the __options()__ array unless the method saves it there. + + The named method must take two arguments, the option name and its + new value. For example, this code is equivalent to (though slower + than) Snit's default handling of __configure__: + + option -font -configuremethod SetOption + method SetOption {option value} { + set options($option) $value + } + + Note that it's possible for any number of options to share a single + __-configuremethod__. + + + __-validatemethod__ *methodName* + + Every locally-defined option may define a __-validatemethod__; it is + called when the option's value is set using the __configure__ or + __configurelist__ methods, just before the __-configuremethod__ (if + any). It is the named method's responsibility to validate the + option's new value, and to throw an error if the value is invalid. + + The named method must take two arguments, the option name and its + new value. For example, this code verifies that __-flag__'s value is + a valid Boolean value: + + option -font -validatemethod CheckBoolean + method CheckBoolean {option value} { + if {![string is boolean -strict $value]} { + error "option $option must have a boolean value." + } + } + + Note that it's possible for any number of options to share a single + __-validatemethod__. + + * __constructor__ *arglist* *body* + + The constructor definition specifies a *body* of code to be executed + when a new instance is created. The *arglist* is a normal Tcl argument + list and may contain default arguments and the __args__ argument. + + As with methods, the arguments __type__, __self__, __selfns__, and + __win__ are defined implicitly, and all type and instance variables are + automatically visible in its *body*. + + If the *definition* doesn't explicitly define the constructor, Snit + defines one implicitly. If the type declares at least one option + (whether locally or by delegation), the default constructor will be + defined as follows: + + constructor {args} { + $self configurelist $args + } + + For standard Tk widget behavior, the argument list should be the single + name __args__, as shown. + + If the *definition* defines neither a constructor nor any options, the + default constructor is defined as follows: + + constructor {} {} + + As with methods, the constructor can call commands from the namespace in + which the type is defined without importing them, e.g., if the type name + is __::parentns::typename__, then the constructor can call + __::parentns::someproc__ just as __someproc__. *Snit 1.x + Incompatibility:* This does not work in Snit 1.x, as it depends on + __namespace path__, a new command in Tcl 8.5. + + * __destructor__ *body* + + The destructor is used to code any actions that must take place when an + instance of the type is destroyed: typically, the destruction of + anything created in the constructor. + + The destructor takes no explicit arguments; as with methods, the + arguments __type__, __self__, __selfns__, and __win__, are defined + implicitly, and all type and instance variables are automatically + visible in its *body*. As with methods, the destructor can call commands + from the namespace in which the type is defined without importing them, + e.g., if the type name is __::parentns::typename__, then the destructor + can call __::parentns::someproc__ just as __someproc__. *Snit 1.x + Incompatibility:* This does not work in Snit 1.x, as it depends on + __namespace path__, a new command in Tcl 8.5. + + * __[proc](../../../../index.md#proc)__ *name* *args* *body* + + Defines a new Tcl procedure in the type's namespace. + + The defined proc differs from a normal Tcl proc in that all type + variables are automatically visible. The proc can access instance + variables as well, provided that it is passed __selfns__ (with precisely + that name) as one of its arguments. + + Although they are not implicitly defined for procs, the argument names + __type__, __self__, and __win__ should be avoided. + + As with methods and typemethods, procs can call commands from the + namespace in which the type is defined without importing them, e.g., if + the type name is __::parentns::typename__, then the proc can call + __::parentns::someproc__ just as __someproc__. *Snit 1.x + Incompatibility:* This does not work in Snit 1.x, as it depends on + __namespace path__, a new command in Tcl 8.5. + + * __delegate__ __method__ *name* __to__ *comp* ?__as__ *target*? + + Delegates method *name* to component *comp*. That is, when method *name* + is called on an instance of this type, the method and its arguments will + be passed to the named component's command instead. That is, the + following statement + + delegate method wag to tail + + is roughly equivalent to this explicitly defined method: + + method wag {args} { + uplevel $tail wag $args + } + + As with methods, the *name* may have multiple tokens; in this case, the + last token of the name is assumed to be the name of the component's + method. + + The optional __as__ clause allows you to specify the delegated method + name and possibly add some arguments: + + delegate method wagtail to tail as "wag briskly" + + A method cannot be both locally defined and delegated. + + __Note:__ All forms of __delegate method__ can delegate to both instance + components and type components. + + * __delegate__ __method__ *name* ?__to__ *comp*? __using__ *pattern* + + In this form of the __delegate__ statement, the __using__ clause is used + to specify the precise form of the command to which method *name* name + is delegated. In this form, the __to__ clause is optional, since the + chosen command might not involve any particular component. + + The value of the __using__ clause is a list that may contain any or all + of the following substitution codes; these codes are substituted with + the described value to build the delegated command prefix. Note that the + following two statements are equivalent: + + delegate method wag to tail + delegate method wag to tail using "%c %m" + + Each element of the list becomes a single element of the delegated + command--it is never reparsed as a string. + + Substitutions: + + + __%%__ + + This is replaced with a single "%". Thus, to pass the string "%c" to + the command as an argument, you'd write "%%c". + + + __%c__ + + This is replaced with the named component's command. + + + __%m__ + + This is replaced with the final token of the method *name*; if the + method *name* has one token, this is identical to __%M__. + + + __%M__ + + This is replaced by the method *name*; if the *name* consists of + multiple tokens, they are joined by space characters. + + + __%j__ + + This is replaced by the method *name*; if the *name* consists of + multiple tokens, they are joined by underscores ("_"). + + + __%t__ + + This is replaced with the fully qualified type name. + + + __%n__ + + This is replaced with the name of the instance's private namespace. + + + __%s__ + + This is replaced with the name of the instance command. + + + __%w__ + + This is replaced with the original name of the instance command; for + Snit widgets and widget adaptors, it will be the Tk window name. It + remains constant, even if the instance command is renamed. + + * __delegate__ __method__ __*__ ?__to__ *comp*? ?__using__ *pattern*? ?__except__ *exceptions*? + + The form __delegate method *__ delegates all unknown method names to the + specified *comp*onent. The __except__ clause can be used to specify a + list of *exceptions*, i.e., method names that will not be so delegated. + The __using__ clause is defined as given above. In this form, the + statement must contain the __to__ clause, the __using__ clause, or both. + + In fact, the "*" can be a list of two or more tokens whose last element + is "*", as in the following example: + + delegate method {tail *} to tail + + This implicitly defines the method __tail__ whose subcommands will be + delegated to the __tail__ component. + + * __delegate__ __option__ *namespec* __to__ *comp* + + * __delegate__ __option__ *namespec* __to__ *comp* __as__ *target* + + * __delegate__ __option__ __*__ __to__ *comp* + + * __delegate__ __option__ __*__ __to__ *comp* __except__ *exceptions* + + Defines a delegated option; the *namespec* is defined as for the + __option__ statement. When the __configure__, __configurelist__, or + __cget__ instance method is used to set or retrieve the option's value, + the equivalent __configure__ or __cget__ command will be applied to the + component as though the option was defined with the following + __-configuremethod__ and __-cgetmethod__: + + method ConfigureMethod {option value} { + $comp configure $option $value + } + + method CgetMethod {option} { + return [$comp cget $option] + } + + Note that delegated options never appear in the __options__ array. + + If the __as__ clause is specified, then the *target* option name is used + in place of *name*. + + The form __delegate option *__ delegates all unknown options to the + specified *comp*onent. The __except__ clause can be used to specify a + list of *exceptions*, i.e., option names that will not be so delegated. + + Warning: options can only be delegated to a component if it supports the + __configure__ and __cget__ instance methods. + + An option cannot be both locally defined and delegated. TBD: Continue + from here. + + * __component__ *comp* ?__-public__ *method*? ?__-inherit__ *flag*? + + Explicitly declares a component called *comp*, and automatically defines + the component's instance variable. + + If the __-public__ option is specified, then the option is made public + by defining a *method* whose subcommands are delegated to the component + e.g., specifying __-public mycomp__ is equivalent to the following: + + component mycomp + delegate method {mymethod *} to mycomp + + If the __-inherit__ option is specified, then *flag* must be a Boolean + value; if *flag* is true then all unknown methods and options will be + delegated to this component. The name __-inherit__ implies that + instances of this new type inherit, in a sense, the methods and options + of the component. That is, __-inherit yes__ is equivalent to: + + component mycomp + delegate option * to mycomp + delegate method * to mycomp + + * __delegate__ __typemethod__ *name* __to__ *comp* ?__as__ *target*? + + Delegates type method *name* to type component *comp*. That is, when + type method *name* is called on this type, the type method and its + arguments will be passed to the named type component's command instead. + That is, the following statement + + delegate typemethod lostdogs to pound + + is roughly equivalent to this explicitly defined method: + + typemethod lostdogs {args} { + uplevel $pound lostdogs $args + } + + As with type methods, the *name* may have multiple tokens; in this case, + the last token of the name is assumed to be the name of the component's + method. + + The optional __as__ clause allows you to specify the delegated method + name and possibly add some arguments: + + delegate typemethod lostdogs to pound as "get lostdogs" + + A type method cannot be both locally defined and delegated. + + * __delegate__ __typemethod__ *name* ?__to__ *comp*? __using__ *pattern* + + In this form of the __delegate__ statement, the __using__ clause is used + to specify the precise form of the command to which type method *name* + name is delegated. In this form, the __to__ clause is optional, since + the chosen command might not involve any particular type component. + + The value of the __using__ clause is a list that may contain any or all + of the following substitution codes; these codes are substituted with + the described value to build the delegated command prefix. Note that the + following two statements are equivalent: + + delegate typemethod lostdogs to pound + delegate typemethod lostdogs to pound using "%c %m" + + Each element of the list becomes a single element of the delegated + command--it is never reparsed as a string. + + Substitutions: + + + __%%__ + + This is replaced with a single "%". Thus, to pass the string "%c" to + the command as an argument, you'd write "%%c". + + + __%c__ + + This is replaced with the named type component's command. + + + __%m__ + + This is replaced with the final token of the type method *name*; if + the type method *name* has one token, this is identical to __%M__. + + + __%M__ + + This is replaced by the type method *name*; if the *name* consists + of multiple tokens, they are joined by space characters. + + + __%j__ + + This is replaced by the type method *name*; if the *name* consists + of multiple tokens, they are joined by underscores ("_"). + + + __%t__ + + This is replaced with the fully qualified type name. + + * __delegate__ __typemethod__ __*__ ?__to__ *comp*? ?__using__ *pattern*? ?__except__ *exceptions*? + + The form __delegate typemethod *__ delegates all unknown type method + names to the specified type component. The __except__ clause can be used + to specify a list of *exceptions*, i.e., type method names that will not + be so delegated. The __using__ clause is defined as given above. In this + form, the statement must contain the __to__ clause, the __using__ + clause, or both. + + __Note:__ By default, Snit interprets __$type foo__, where __foo__ is + not a defined type method, as equivalent to __$type create foo__, where + __foo__ is the name of a new instance of the type. If you use __delegate + typemethod *__, then the __create__ type method must always be used + explicitly. + + The "*" can be a list of two or more tokens whose last element is "*", + as in the following example: + + delegate typemethod {tail *} to tail + + This implicitly defines the type method __tail__ whose subcommands will + be delegated to the __tail__ type component. + + * __typecomponent__ *comp* ?__-public__ *typemethod*? ?__-inherit__ *flag*? + + Explicitly declares a type component called *comp*, and automatically + defines the component's type variable. A type component is an arbitrary + command to which type methods and instance methods can be delegated; the + command's name is stored in a type variable. + + If the __-public__ option is specified, then the type component is made + public by defining a *typemethod* whose subcommands are delegated to the + type component, e.g., specifying __-public mytypemethod__ is equivalent + to the following: + + typecomponent mycomp + delegate typemethod {mytypemethod *} to mycomp + + If the __-inherit__ option is specified, then *flag* must be a Boolean + value; if *flag* is true then all unknown type methods will be delegated + to this type component. (See the note on "delegate typemethod *", + above.) The name __-inherit__ implies that this type inherits, in a + sense, the behavior of the type component. That is, __-inherit yes__ is + equivalent to: + + typecomponent mycomp + delegate typemethod * to mycomp + + * __pragma__ ?*options...*? + + The __pragma__ statement provides control over how Snit generates a + type. It takes the following options; in each case, *flag* must be a + Boolean value recognized by Tcl, e.g., __0__, __1__, __yes__, __no__, + and so on. + + By setting the __-hastypeinfo__, __-hastypedestroy__, and + __-hasinstances__ pragmas to false and defining appropriate type + methods, you can create an ensemble command without any extraneous + behavior. + + + __-canreplace__ *flag* + + If false (the default) Snit will not create an instance of a + __snit::type__ that has the same name as an existing command; this + prevents subtle errors. Setting this pragma to true restores the + behavior of Snit V0.93 and earlier versions. + + + __-hastypeinfo__ *flag* + + If true (the default), the generated type will have a type method + called __[info](../../../../index.md#info)__ that is used for type + introspection; the __[info](../../../../index.md#info)__ type method + is documented below. If false, it will not. + + + __-hastypedestroy__ *flag* + + If true (the default), the generated type will have a type method + called __destroy__ that is used to destroy the type and all of its + instances. The __destroy__ type method is documented below. If + false, it will not. + + + __-hastypemethods__ *flag* + + If true (the default), the generated type's type command will have + subcommands (type methods) as usual. If false, the type command will + serve only to create instances of the type; the first argument is + the instance name. + + This pragma and __-hasinstances__ cannot both be set false. + + + __-hasinstances__ *flag* + + If true (the default), the generated type will have a type method + called __create__ that is used to create instances of the type, + along with a variety of instance-related features. If false, it will + not. + + This pragma and __-hastypemethods__ cannot both be set false. + + + __-hasinfo__ *flag* + + If true (the default), instances of the generated type will have an + instance method called __info__ that is used for instance + introspection; the __info__ method is documented below. If false, it + will not. + + + __-simpledispatch__ *flag* + + This pragma is intended to make simple, heavily-used abstract data + types (e.g., stacks and queues) more efficient. + + If false (the default), instance methods are dispatched normally. If + true, a faster dispatching scheme is used instead. The speed comes + at a price; with __-simpledispatch yes__ you get the following + limitations: + + Methods cannot be delegated. + + __uplevel__ and __upvar__ do not work as expected: the caller's + scope is two levels up rather than one. + + The option-handling methods (__cget__, __configure__, and + __configurelist__) are very slightly slower. + + * __expose__ *comp* + + * __expose__ *comp* __as__ *method* + + __Deprecated.__ To expose component *comp* publicly, use __component__'s + __-public__ option. + + * __onconfigure__ *name* *arglist* *body* + + __Deprecated.__ Define __option__'s __-configuremethod__ option instead. + + As of version 0.95, the following definitions, + + option -myoption + onconfigure -myoption {value} { + # Code to save the option's value + } + + are implemented as follows: + + option -myoption -configuremethod _configure-myoption + method _configure-myoption {_option value} { + # Code to save the option's value + } + + * __oncget__ *name* *body* + + __Deprecated.__ Define __option__'s __-cgetmethod__ option instead. + + As of version 0.95, the following definitions, + + option -myoption + oncget -myoption { + # Code to return the option's value + } + + are implemented as follows: + + option -myoption -cgetmethod _cget-myoption + method _cget-myoption {_option} { + # Code to return the option's value + } + + - __snit::widget__ *name* *definition* + + This command defines a Snit megawidget type with the specified *name*. The + *definition* is defined as for __snit::type__. A __snit::widget__ differs + from a __snit::type__ in these ways: + + Every instance of a __snit::widget__ has an automatically-created component + called __hull__, which is normally a Tk frame widget. Other widgets created + as part of the megawidget will be created within this widget. + + The hull component is initially created with the requested widget name; then + Snit does some magic, renaming the hull component and installing its own + instance command in its place. The hull component's new name is saved in an + instance variable called __hull__. + + The name of an instance must be valid Tk window name, and the parent window + must exist. + + A __snit::widget__ definition can include any of statements allowed in a + __snit::type__ definition, and may also include the following: + + * __widgetclass__ *name* + + Sets the __snit::widget__'s widget class to *name*, overriding the + default. See [The Tk Option Database](#subsection9) for more + information. + + * __hulltype__ *type* + + Determines the kind of widget used as the __snit::widget__'s hull. The + *type* may be __frame__ (the default), __toplevel__, __labelframe__; the + qualified equivalents of these, __tk::frame__, __tk::toplevel__, and + __tk::labelframe__; or, if available, the equivalent Tile widgets: + __ttk::frame__, __ttk::toplevel__, and __ttk::labelframe__. In practice, + any widget that supports the __-class__ option can be used as a hull + widget by __lappend__'ing its name to the variable __snit::hulltypes__. + + - __snit::widgetadaptor__ *name* *definition* + + This command defines a Snit megawidget type with the specified name. It + differs from __snit::widget__ in that the instance's __hull__ component is + not created automatically, but is created in the constructor and installed + using the __installhull__ command. Once the hull is installed, its instance + command is renamed and replaced as with normal __snit::widget__s. The + original command is again accessible in the instance variable __hull__. + + Note that in general it is not possible to change the *widget class* of a + __snit::widgetadaptor__'s hull widget. + + See [The Tk Option Database](#subsection9) for information on how + __snit::widgetadaptor__s interact with the option database. + + - __snit::typemethod__ *type* *name* *arglist* *body* + + Defines a new type method (or redefines an existing type method) for a + previously existing *type*. + + - __snit::method__ *type* *name* *arglist* *body* + + Defines a new instance method (or redefines an existing instance method) for + a previously existing *type*. Note that delegated instance methods can't be + redefined. + + - __snit::macro__ *name* *arglist* *body* + + Defines a Snit macro with the specified *name*, *arglist*, and *body*. + Macros are used to define new type and widget definition statements in terms + of the statements defined in this man page. + + A macro is simply a Tcl proc that is defined in the slave interpreter used + to compile type and widget definitions. Thus, macros have access to all of + the type and widget definition statements. See [Macros and + Meta-programming](#subsection10) for more details. + + The macro *name* cannot be the same as any standard Tcl command, or any Snit + type or widget definition statement, e.g., you can't redefine the + __[method](../../../../index.md#method)__ or __delegate__ statements, or the + standard __[set](../../../../index.md#set)__, + __[list](../../../../index.md#list)__, or + __[string](../../../../index.md#string)__ commands. + + - __snit::compile__ *which* *type* *body* + + Snit defines a type, widget, or widgetadaptor by "compiling" the definition + into a Tcl script; this script is then evaluated in the Tcl interpreter, + which actually defines the new type. + + This command exposes the "compiler". Given a definition *body* for the named + *type*, where *which* is __type__, __widget__, or __widgetadaptor__, + __snit::compile__ returns a list of two elements. The first element is the + fully qualified type name; the second element is the definition script. + + __snit::compile__ is useful when additional processing must be done on the + Snit-generated code--if it must be instrumented, for example, or run through + the TclDevKit compiler. In addition, the returned script could be saved in a + ".tcl" file and used to define the type as part of an application or + library, thus saving the compilation overhead at application start-up. Note + that the same version of Snit must be used at run-time as at compile-time. + +## The Type Command + +A type or widget definition creates a type command, which is used to create +instances of the type. The type command has this form: + + - __$type__ *typemethod* *args*... + + The *typemethod* can be any of the [Standard Type Methods](#subsection3) + (e.g., __create__), or any type method defined in the type definition. The + subsequent *args* depend on the specific *typemethod* chosen. + + The type command is most often used to create new instances of the type; + hence, the __create__ method is assumed if the first argument to the type + command doesn't name a valid type method, unless the type definition + includes __delegate typemethod *__ or the __-hasinstances__ pragma is set to + false. + + Furthermore, if the __-hastypemethods__ pragma is false, then Snit type + commands can be called with no arguments at all; in this case, the type + command creates an instance with an automatically generated name. In other + words, provided that the __-hastypemethods__ pragma is false and the type + has instances, the following commands are equivalent: + + snit::type dog { ... } + + set mydog [dog create %AUTO%] + set mydog [dog %AUTO%] + set mydog [dog] + + This doesn't work for Snit widgets, for obvious reasons. + + *Snit 1.x Incompatibility:* In Snit 1.x, the above behavior is available + whether __-hastypemethods__ is true (the default) or false. + +## Standard Type Methods + +In addition to any type methods in the type's definition, all type and widget +commands will usually have at least the following subcommands: + + - __$type__ __create__ *name* ?*option* *value* ...? + + Creates a new instance of the type, giving it the specified *name* and + calling the type's constructor. + + For __snit::type__s, if *name* is not a fully-qualified command name, it is + assumed to be a name in the namespace in which the call to __snit::type__ + appears. The method returns the fully-qualified instance name. + + For __snit::widget__s and __snit::widgetadaptor__s, *name* must be a valid + widget name; the method returns the widget name. + + So long as *name* does not conflict with any defined type method name the + __create__ keyword may be omitted, unless the type definition includes + __delegate typemethod *__ or the __-hasinstances__ pragma is set to false. + + If the *name* includes the string __%AUTO%__, it will be replaced with the + string __$type$counter__ where __$type__ is the type name and __$counter__ + is a counter that increments each time __%AUTO%__ is used for this type. + + By default, any arguments following the *name* will be a list of *option* + names and their *value*s; however, a type's constructor can specify a + different argument list. + + As of Snit V0.95, __create__ will throw an error if the *name* is the same + as any existing command--note that this was always true for + __snit::widget__s and __snit::widgetadaptor__s. You can restore the previous + behavior using the __-canreplace__ pragma. + + - __$type__ __info typevars__ ?*pattern*? + + Returns a list of the type's type variables (excluding Snit internal + variables); all variable names are fully-qualified. + + If *pattern* is given, it's used as a __string match__ pattern; only names + that match the pattern are returned. + + - __$type__ __info typemethods__ ?*pattern*? + + Returns a list of the names of the type's type methods. If the type has + hierarchical type methods, whether locally-defined or delegated, only the + first word of each will be included in the list. + + If the type definition includes __delegate typemethod *__, the list will + include only the names of those implicitly delegated type methods that have + been called at least once and are still in the type method cache. + + If *pattern* is given, it's used as a __string match__ pattern; only names + that match the pattern are returned. + + - __$type__ __info args__ *method* + + Returns a list containing the names of the arguments to the type's *method*, + in order. This method cannot be applied to delegated type methods. + + - __$type__ __info body__ *method* + + Returns the body of typemethod *method*. This method cannot be applied to + delegated type methods. + + - __$type__ __info default__ *method* *aname* *varname* + + Returns a boolean value indicating whether the argument *aname* of the + type's *method* has a default value (__true__) or not (__false__). If the + argument has a default its value is placed into the variable *varname*. + + - __$type__ __info instances__ ?*pattern*? + + Returns a list of the type's instances. For __snit::type__s, it will be a + list of fully-qualified instance names; for __snit::widget__s, it will be a + list of Tk widget names. + + If *pattern* is given, it's used as a __string match__ pattern; only names + that match the pattern are returned. + + *Snit 1.x Incompatibility:* In Snit 1.x, the full multi-word names of + hierarchical type methods are included in the return value. + + - __$type__ __destroy__ + + Destroys the type's instances, the type's namespace, and the type command + itself. + +## The Instance Command + +A Snit type or widget's __create__ type method creates objects of the type; each +object has a unique name that is also a Tcl command. This command is used to +access the object's methods and data, and has this form: + + - __$object__ *method* *args...* + + The *method* can be any of the [Standard Instance Methods](#subsection5), or + any instance method defined in the type definition. The subsequent *args* + depend on the specific *method* chosen. + +## Standard Instance Methods + +In addition to any delegated or locally-defined instance methods in the type's +definition, all Snit objects will have at least the following subcommands: + + - __$object__ __configure__ ?*option*? ?*value*? ... + + Assigns new values to one or more options. If called with one argument, an + *option* name, returns a list describing the option, as Tk widgets do; if + called with no arguments, returns a list of lists describing all options, as + Tk widgets do. + + Warning: This information will be available for delegated options only if + the component to which they are delegated has a __configure__ method that + returns this same kind of information. + + Note: Snit defines this method only if the type has at least one option. + + - __$object__ __configurelist__ *optionlist* + + Like __configure__, but takes one argument, a list of options and their + values. It's mostly useful in the type constructor, but can be used + anywhere. + + Note: Snit defines this method only if the type has at least one option. + + - __$object__ __cget__ *option* + + Returns the option's value. + + Note: Snit defines this method only if the type has at least one option. + + - __$object__ __destroy__ + + Destroys the object, calling the __destructor__ and freeing all related + memory. + + *Note:* The __destroy__ method isn't defined for __snit::widget__ or + __snit::widgetadaptor__ objects; instances of these are destroyed by calling + __[Tk](../../../../index.md#tk)__'s __destroy__ command, just as normal + widgets are. + + - __$object__ __info type__ + + Returns the instance's type. + + - __$object__ __info vars__ ?*pattern*? + + Returns a list of the object's instance variables (excluding Snit internal + variables). The names are fully qualified. + + If *pattern* is given, it's used as a __string match__ pattern; only names + that match the pattern are returned. + + - __$object__ __info typevars__ ?*pattern*? + + Returns a list of the object's type's type variables (excluding Snit + internal variables). The names are fully qualified. + + If *pattern* is given, it's used as a __string match__ pattern; only names + that match the pattern are returned. + + - __$object__ __info typemethods__ ?*pattern*? + + Returns a list of the names of the type's type methods. If the type has + hierarchical type methods, whether locally-defined or delegated, only the + first word of each will be included in the list. + + If the type definition includes __delegate typemethod *__, the list will + include only the names of those implicitly delegated type methods that have + been called at least once and are still in the type method cache. + + If *pattern* is given, it's used as a __string match__ pattern; only names + that match the pattern are returned. + + *Snit 1.x Incompatibility:* In Snit 1.x, the full multi-word names of + hierarchical type methods are included in the return value. + + - __$object__ __info options__ ?*pattern*? + + Returns a list of the object's option names. This always includes local + options and explicitly delegated options. If unknown options are delegated + as well, and if the component to which they are delegated responds to + __$object configure__ like Tk widgets do, then the result will include all + possible unknown options that can be delegated to the component. + + If *pattern* is given, it's used as a __string match__ pattern; only names + that match the pattern are returned. + + Note that the return value might be different for different instances of the + same type, if component object types can vary from one instance to another. + + - __$object__ __info methods__ ?*pattern*? + + Returns a list of the names of the instance's methods. If the type has + hierarchical methods, whether locally-defined or delegated, only the first + word of each will be included in the list. + + If the type definition includes __delegate method *__, the list will include + only the names of those implicitly delegated methods that have been called + at least once and are still in the method cache. + + If *pattern* is given, it's used as a __string match__ pattern; only names + that match the pattern are returned. + + *Snit 1.x Incompatibility:* In Snit 1.x, the full multi-word names of + hierarchical type methods are included in the return value. + + - __$object__ __info args__ *method* + + Returns a list containing the names of the arguments to the instance's + *method*, in order. This method cannot be applied to delegated methods. + + - __$object__ __info body__ *method* + + Returns the body of the instance's method *method*. This method cannot be + applied to delegated methods. + + - __$object__ __info default__ *method* *aname* *varname* + + Returns a boolean value indicating whether the argument *aname* of the + instance's *method* has a default value (__true__) or not (__false__). If + the argument has a default its value is placed into the variable *varname*. + +## Commands for use in Object Code + +Snit defines the following commands for use in your object code: that is, for +use in type methods, instance methods, constructors, destructors, onconfigure +handlers, oncget handlers, and procs. They do not reside in the ::snit:: +namespace; instead, they are created with the type, and can be used without +qualification. + + - __mymethod__ *name* ?*args...*? + + The __mymethod__ command is used for formatting callback commands to be + passed to other objects. It returns a command that when called will invoke + method *name* with the specified arguments, plus of course any arguments + added by the caller. In other words, both of the following commands will + cause the object's __dosomething__ method to be called when the __$button__ + is pressed: + + $button configure -command [list $self dosomething myargument] + + $button configure -command [mymethod dosomething myargument] + + The chief distinction between the two is that the latter form will not break + if the object's command is renamed. + + - __mytypemethod__ *name* ?*args...*? + + The __mytypemethod__ command is used for formatting callback commands to be + passed to other objects. It returns a command that when called will invoke + type method *name* with the specified arguments, plus of course any + arguments added by the caller. In other words, both of the following + commands will cause the object's __dosomething__ type method to be called + when __$button__ is pressed: + + $button configure -command [list $type dosomething myargument] + + $button configure -command [mytypemethod dosomething myargument] + + Type commands cannot be renamed, so in practice there's little difference + between the two forms. __mytypemethod__ is provided for parallelism with + __mymethod__. + + - __myproc__ *name* ?*args...*? + + The __myproc__ command is used for formatting callback commands to be passed + to other objects. It returns a command that when called will invoke the type + proc *name* with the specified arguments, plus of course any arguments added + by the caller. In other words, both of the following commands will cause the + object's __dosomething__ proc to be called when __$button__ is pressed: + + $button configure -command [list ${type}::dosomething myargument] + + $button configure -command [myproc dosomething myargument] + + - __myvar__ *name* + + Given an instance variable name, returns the fully qualified name. Use this + if you're passing the variable to some other object, e.g., as a + __-textvariable__ to a Tk label widget. + + - __mytypevar__ *name* + + Given an type variable name, returns the fully qualified name. Use this if + you're passing the variable to some other object, e.g., as a + __-textvariable__ to a Tk label widget. + + - __from__ *argvName* *option* ?*defvalue*? + + The __from__ command plucks an option value from a list of options and their + values, such as is passed into a type's __constructor__. *argvName* must be + the name of a variable containing such a list; *option* is the name of the + specific option. + + __from__ looks for *option* in the option list. If it is found, it and its + value are removed from the list, and the value is returned. If *option* + doesn't appear in the list, then the *defvalue* is returned. If the option + is locally-defined option, and *defvalue* is not specified, then the + option's default value as specified in the type definition will be returned + instead. + + - __install__ *compName* __using__ *objType* *objName* *args...* + + Creates a new object of type *objType* called *objName* and installs it as + component *compName*, as described in [Components and + Delegation](#subsection7). Any additional *args...* are passed along with + the name to the *objType* command. If this is a __snit::type__, then the + following two commands are equivalent: + + install myComp using myObjType $self.myComp args... + + set myComp [myObjType $self.myComp args...] + + Note that whichever method is used, *compName* must still be declared in the + type definition using __component__, or must be referenced in at least one + __delegate__ statement. + + If this is a __snit::widget__ or __snit::widgetadaptor__, and if options + have been delegated to component *compName*, then those options will receive + default values from the Tk option database. Note that it doesn't matter + whether the component to be installed is a widget or not. See [The Tk Option + Database](#subsection9) for more information. + + __install__ cannot be used to install type components; just assign the type + component's command name to the type component's variable instead. + + - __installhull__ __using__ *widgetType* *args...* + + - __installhull__ *name* + + The constructor of a __snit::widgetadaptor__ must create a widget to be the + object's hull component; the widget is installed as the hull component using + this command. Note that the installed widget's name must be __$win__. This + command has two forms. + + The first form specifies the *widgetType* and the *args...* (that is, the + hardcoded option list) to use in creating the hull. Given this form, + __installhull__ creates the hull widget, and initializes any options + delegated to the hull from the Tk option database. + + In the second form, the hull widget has already been created; note that its + name must be "$win". In this case, the Tk option database is *not* queried + for any options delegated to the hull. The longer form is preferred; + however, the shorter form allows the programmer to adapt a widget created + elsewhere, which is sometimes useful. For example, it can be used to adapt a + "page" widget created by a __BWidgets__ tabbed notebook or pages manager + widget. + + See [The Tk Option Database](#subsection9) for more information about + __snit::widgetadaptor__s and the option database. + + - __variable__ *name* + + Normally, instance variables are defined in the type definition along with + the options, methods, and so forth; such instance variables are + automatically visible in all instance code (e.g., method bodies). However, + instance code can use the __variable__ command to declare instance variables + that don't appear in the type definition, and also to bring variables from + other namespaces into scope in the usual way. + + It's generally clearest to define all instance variables in the type + definition, and omit declaring them in methods and so forth. + + Note that this is an instance-specific version of the standard Tcl + __::variable__ command. + + - __typevariable__ *name* + + Normally, type variables are defined in the type definition, along with the + instance variables; such type variables are automatically visible in all of + the type's code. However, type methods, instance methods and so forth can + use __typevariable__ to declare type variables that don't appear in the type + definition. + + It's generally clearest to declare all type variables in the type + definition, and omit declaring them in methods, type methods, etc. + + - __varname__ *name* + + __Deprecated.__ Use __myvar__ instead. + + Given an instance variable name, returns the fully qualified name. Use this + if you're passing the variable to some other object, e.g., as a + __-textvariable__ to a Tk label widget. + + - __typevarname__ *name* + + __Deprecated.__ Use __mytypevar__ instead. + + Given a type variable name, returns the fully qualified name. Use this if + you're passing the type variable to some other object, e.g., as a + __-textvariable__ to a Tk label widget. + + - __codename__ *name* + + __Deprecated.__ Use __myproc__ instead. Given the name of a proc (but not a + type or instance method), returns the fully-qualified command name, suitable + for passing as a callback. + +## Components and Delegation + +When an object includes other objects, as when a toolbar contains buttons or a +GUI object contains an object that references a database, the included object is +called a component. The standard way to handle component objects owned by a Snit +object is to declare them using __component__, which creates a component +instance variable. In the following example, a __dog__ object has a __tail__ +object: + + snit::type dog { + component mytail + + constructor {args} { + set mytail [tail %AUTO% -partof $self] + $self configurelist $args + } + + method wag {} { + $mytail wag + } + } + + snit::type tail { + option -length 5 + option -partof + method wag {} { return "Wag, wag, wag."} + } + +Because the __tail__ object's name is stored in an instance variable, it's +easily accessible in any method. + +The __install__ command provides an alternate way to create and install the +component: + + snit::type dog { + component mytail + + constructor {args} { + install mytail using tail %AUTO% -partof $self + $self configurelist $args + } + + method wag {} { + $mytail wag + } + } + +For __snit::type__s, the two methods are equivalent; for __snit::widget__s and +__snit::widgetadaptor__s, the __install__ command properly initializes the +widget's options by querying [The Tk Option Database](#subsection9). + +In the above examples, the __dog__ object's __wag__ method simply calls the +__tail__ component's __wag__ method. In OO jargon, this is called delegation. +Snit provides an easier way to do this: + + snit::type dog { + delegate method wag to mytail + + constructor {args} { + install mytail using tail %AUTO% -partof $self + $self configurelist $args + } + } + +The __delegate__ statement in the type definition implicitly defines the +instance variable __mytail__ to hold the component's name (though it's good form +to use __component__ to declare it explicitly); it also defines the __dog__ +object's __wag__ method, delegating it to the __mytail__ component. + +If desired, all otherwise unknown methods can be delegated to a specific +component: + + snit::type dog { + delegate method * to mytail + + constructor {args} { + set mytail [tail %AUTO% -partof $self] + $self configurelist $args + } + + method bark { return "Bark, bark, bark!" } + } + +In this case, a __dog__ object will handle its own __bark__ method; but __wag__ +will be passed along to __mytail__. Any other method, being recognized by +neither __dog__ nor __tail__, will simply raise an error. + +Option delegation is similar to method delegation, except for the interactions +with the Tk option database; this is described in [The Tk Option +Database](#subsection9). + +## Type Components and Delegation + +The relationship between type components and instance components is identical to +that between type variables and instance variables, and that between type +methods and instance methods. Just as an instance component is an instance +variable that holds the name of a command, so a type component is a type +variable that holds the name of a command. In essence, a type component is a +component that's shared by every instance of the type. + +Just as __delegate method__ can be used to delegate methods to instance +components, as described in [Components and Delegation](#subsection7), so +__delegate typemethod__ can be used to delegate type methods to type components. + +Note also that as of Snit 0.95 __delegate method__ can delegate methods to both +instance components and type components. + +## The Tk Option Database + +This section describes how Snit interacts with the Tk option database, and +assumes the reader has a working knowledge of the option database and its uses. +The book *Practical Programming in Tcl and Tk* by Welch et al has a good +introduction to the option database, as does *Effective Tcl/Tk Programming*. + +Snit is implemented so that most of the time it will simply do the right thing +with respect to the option database, provided that the widget developer does the +right thing by Snit. The body of this section goes into great deal about what +Snit requires. The following is a brief statement of the requirements, for +reference. + + - If the __snit::widget__'s default widget class is not what is desired, set + it explicitly using __widgetclass__ in the widget definition. + + - When defining or delegating options, specify the resource and class names + explicitly when if the defaults aren't what you want. + + - Use __installhull using__ to install the hull for __snit::widgetadaptor__s. + + - Use __install__ to install all other components. + +The interaction of Tk widgets with the option database is a complex thing; the +interaction of Snit with the option database is even more so, and repays +attention to detail. + +__Setting the widget class:__ Every Tk widget has a widget class. For Tk +widgets, the widget class name is the just the widget type name with an initial +capital letter, e.g., the widget class for __button__ widgets is "Button". + +Similarly, the widget class of a __snit::widget__ defaults to the unqualified +type name with the first letter capitalized. For example, the widget class of + + snit::widget ::mylibrary::scrolledText { ... } + +is "ScrolledText". The widget class can also be set explicitly using the +__widgetclass__ statement within the __snit::widget__ definition. + +Any widget can be used as the __hulltype__ provided that it supports the +__-class__ option for changing its widget class name. See the discussion of the +__hulltype__ command, above. The user may pass __-class__ to the widget at +instantion. + +The widget class of a __snit::widgetadaptor__ is just the widget class of its +hull widget; this cannot be changed unless the hull widget supports __-class__, +in which case it will usually make more sense to use __snit::widget__ rather +than __snit::widgetadaptor__. + +__Setting option resource names and classes:__ In Tk, every option has three +names: the option name, the resource name, and the class name. The option name +begins with a hyphen and is all lowercase; it's used when creating widgets, and +with the __configure__ and __cget__ commands. + +The resource and class names are used to initialize option default values by +querying the Tk option database. The resource name is usually just the option +name minus the hyphen, but may contain uppercase letters at word boundaries; the +class name is usually just the resource name with an initial capital, but not +always. For example, here are the option, resource, and class names for several +__[text](../../../../index.md#text)__ widget options: + + -background background Background + -borderwidth borderWidth BorderWidth + -insertborderwidth insertBorderWidth BorderWidth + -padx padX Pad + +As is easily seen, sometimes the resource and class names can be inferred from +the option name, but not always. + +Snit options also have a resource name and a class name. By default, these names +follow the rule given above: the resource name is the option name without the +hyphen, and the class name is the resource name with an initial capital. This is +true for both locally-defined options and explicitly delegated options: + + snit::widget mywidget { + option -background + delegate option -borderwidth to hull + delegate option * to text + # ... + } + +In this case, the widget class name is "Mywidget". The widget has the following +options: __-background__, which is locally defined, and __-borderwidth__, which +is explicitly delegated; all other widgets are delegated to a component called +"text", which is probably a Tk __[text](../../../../index.md#text)__ widget. If +so, __mywidget__ has all the same options as a +__[text](../../../../index.md#text)__ widget. The option, resource, and class +names are as follows: + + -background background Background + -borderwidth borderwidth Borderwidth + -padx padX Pad + +Note that the locally defined option, __-background__, happens to have the same +three names as the standard Tk __-background__ option; and __-pad__, which is +delegated implicitly to the __text__ component, has the same three names for +__mywidget__ as it does for the __[text](../../../../index.md#text)__ widget. +__-borderwidth__, on the other hand, has different resource and class names than +usual, because the internal word "width" isn't capitalized. For consistency, it +should be; this is done as follows: + + snit::widget mywidget { + option -background + delegate option {-borderwidth borderWidth} to hull + delegate option * to text + # ... + } + +The class name will default to "BorderWidth", as expected. + +Suppose, however, that __mywidget__ also delegated __-padx__ and __-pady__ to +the hull. In this case, both the resource name and the class name must be +specified explicitly: + + snit::widget mywidget { + option -background + delegate option {-borderwidth borderWidth} to hull + delegate option {-padx padX Pad} to hull + delegate option {-pady padY Pad} to hull + delegate option * to text + # ... + } + +__Querying the option database:__ If you set your widgetclass and option names +as described above, Snit will query the option database when each instance is +created, and will generally do the right thing when it comes to querying the +option database. The remainder of this section goes into the gory details. + +__Initializing locally defined options:__ When an instance of a snit::widget is +created, its locally defined options are initialized as follows: each option's +resource and class names are used to query the Tk option database. If the result +is non-empty, it is used as the option's default; otherwise, the default +hardcoded in the type definition is used. In either case, the default can be +overridden by the caller. For example, + + option add *Mywidget.texture pebbled + + snit::widget mywidget { + option -texture smooth + # ... + } + + mywidget .mywidget -texture greasy + +Here, __-texture__ would normally default to "smooth", but because of the entry +added to the option database it defaults to "pebbled". However, the caller has +explicitly overridden the default, and so the new widget will be "greasy". + +__Initializing options delegated to the hull:__ A __snit::widget__'s hull is a +widget, and given that its class has been set it is expected to query the option +database for itself. The only exception concerns options that are delegated to +it with a different name. Consider the following code: + + option add *Mywidget.borderWidth 5 + option add *Mywidget.relief sunken + option add *Mywidget.hullbackground red + option add *Mywidget.background green + + snit::widget mywidget { + delegate option -borderwidth to hull + delegate option -hullbackground to hull as -background + delegate option * to hull + # ... + } + + mywidget .mywidget + + set A [.mywidget cget -relief] + set B [.mywidget cget -hullbackground] + set C [.mywidget cget -background] + set D [.mywidget cget -borderwidth] + +The question is, what are the values of variables A, B, C and D? + +The value of A is "sunken". The hull is a Tk frame that has been given the +widget class "Mywidget"; it will automatically query the option database and +pick up this value. Since the __-relief__ option is implicitly delegated to the +hull, Snit takes no action. + +The value of B is "red". The hull will automatically pick up the value "green" +for its __-background__ option, just as it picked up the __-relief__ value. +However, Snit knows that __-hullbackground__ is mapped to the hull's +__-background__ option; hence, it queries the option database for +__-hullbackground__ and gets "red" and updates the hull accordingly. + +The value of C is also "red", because __-background__ is implicitly delegated to +the hull; thus, retrieving it is the same as retrieving __-hullbackground__. +Note that this case is unusual; in practice, __-background__ would probably be +explicitly delegated to some other component. + +The value of D is "5", but not for the reason you think. Note that as it is +defined above, the resource name for __-borderwidth__ defaults to "borderwidth", +whereas the option database entry is "borderWidth". As with __-relief__, the +hull picks up its own __-borderwidth__ option before Snit does anything. Because +the option is delegated under its own name, Snit assumes that the correct thing +has happened, and doesn't worry about it any further. + +For __snit::widgetadaptor__s, the case is somewhat altered. Widget adaptors +retain the widget class of their hull, and the hull is not created automatically +by Snit. Instead, the __snit::widgetadaptor__ must call __installhull__ in its +constructor. The normal way to do this is as follows: + + snit::widgetadaptor mywidget { + # ... + constructor {args} { + # ... + installhull using text -foreground white + # + } + #... + } + +In this case, the __installhull__ command will create the hull using a command +like this: + + set hull [text $win -foreground white] + +The hull is a __[text](../../../../index.md#text)__ widget, so its widget class +is "Text". Just as with __snit::widget__ hulls, Snit assumes that it will pick +up all of its normal option values automatically; options delegated from a +different name are initialized from the option database in the same way. + +__Initializing options delegated to other components:__ Non-hull components are +matched against the option database in two ways. First, a component widget +remains a widget still, and therefore is initialized from the option database in +the usual way. Second, the option database is queried for all options delegated +to the component, and the component is initialized accordingly--provided that +the __install__ command is used to create it. + +Before option database support was added to Snit, the usual way to create a +component was to simply create it in the constructor and assign its command name +to the component variable: + + snit::widget mywidget { + delegate option -background to myComp + + constructor {args} { + set myComp [text $win.text -foreground black] + } + } + +The drawback of this method is that Snit has no opportunity to initialize the +component properly. Hence, the following approach is now used: + + snit::widget mywidget { + delegate option -background to myComp + + constructor {args} { + install myComp using text $win.text -foreground black + } + } + +The __install__ command does the following: + + - Builds a list of the options explicitly included in the __install__ command + -- in this case, __-foreground__. + + - Queries the option database for all options delegated explicitly to the + named component. + + - Creates the component using the specified command, after inserting into it a + list of options and values read from the option database. Thus, the + explicitly included options (__-foreground__) will override anything read + from the option database. + + - If the widget definition implicitly delegated options to the component using + __delegate option *__, then Snit calls the newly created component's + __configure__ method to receive a list of all of the component's options. + From this Snit builds a list of options implicitly delegated to the + component that were not explicitly included in the __install__ command. For + all such options, Snit queries the option database and configures the + component accordingly. + +__Non-widget components:__ The option database is never queried for +__snit::type__s, since it can only be queried given a Tk widget name. However, +__snit::widget__s can have non-widget components. And if options are delegated +to those components, and if the __install__ command is used to install those +components, then they will be initialized from the option database just as +widget components are. + +## Macros and Meta-programming + +The __snit::macro__ command enables a certain amount of meta-programming with +Snit classes. For example, suppose you like to define properties: instance +variables that have set/get methods. Your code might look like this: + + snit::type dog { + variable mood happy + + method getmood {} { + return $mood + } + + method setmood {newmood} { + set mood $newmood + } + } + +That's nine lines of text per property. Or, you could define the following +__snit::macro__: + + snit::macro property {name initValue} { + variable $name $initValue + + method get$name {} "return $name" + + method set$name {value} "set $name \$value" + } + +Note that a __snit::macro__ is just a normal Tcl proc defined in the slave +interpreter used to compile type and widget definitions; as a result, it has +access to all the commands used to define types and widgets. + +Given this new macro, you can define a property in one line of code: + + snit::type dog { + property mood happy + } + +Within a macro, the commands __variable__ and +__[proc](../../../../index.md#proc)__ refer to the Snit type-definition +commands, not the standard Tcl commands. To get the standard Tcl commands, use +___variable__ and ___proc__. + +Because a single slave interpreter is used for compiling all Snit types and +widgets in the application, there's the possibility of macro name collisions. If +you're writing a reuseable package using Snit, and you use some +__snit::macro__s, define them in your package namespace: + + snit::macro mypkg::property {name initValue} { ... } + + snit::type dog { + mypkg::property mood happy + } + +This leaves the global namespace open for application authors. + +## Validation Types + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__ is used to validate that a Tcl +value is an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + snit::integer validate 5 ;# Does nothing + snit::integer validate 5.0 ;# Throws an error (not an integer!) + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error. + +Snit defines a family of validation types, all of which are implemented as +__snit::type__'s. They can be used as is; in addition, their instances serve as +parameterized subtypes. For example, a probability is a number between 0.0 and +1.0 inclusive: + + snit::double probability -min 0.0 -max 1.0 + +The example above creates an instance of __snit::double__--a validation +subtype--called __probability__, which can be used to validate probability +values: + + probability validate 0.5 ;# Does nothing + probability validate 7.9 ;# Throws an error + +Validation subtypes can be defined explicitly, as in the above example; when a +locally-defined option's __-type__ is specified, they may also be created on the +fly: + + snit::enum ::dog::breed -values {mutt retriever sheepdog} + + snit::type dog { + # Define subtypes on the fly... + option -breed -type { + snit::enum -values {mutt retriever sheepdog} + } + + # Or use predefined subtypes... + option -breed -type ::dog::breed + } + +Any object that has a __validate__ method with the semantics described above can +be used as a validation type; see [Defining Validation Types](#subsection12) for +information on how to define new ones. + +Snit defines the following validation types: + + - __snit::boolean__ __validate__ ?*value*? + + - __snit::boolean__ *name* + + Validates Tcl boolean values: 1, 0, __on__, __off__, __yes__, __no__, + __true__, __false__. It's possible to define subtypes--that is, + instances--of __snit::boolean__, but as it has no options there's no reason + to do so. + + - __snit::double__ __validate__ ?*value*? + + - __snit::double__ *name* ?*option* *value*...? + + Validates floating-point values. Subtypes may be created with the following + options: + + * __-min__ *min* + + Specifies a floating-point minimum bound; a value is invalid if it is + strictly less than *min*. + + * __-max__ *max* + + Specifies a floating-point maximum bound; a value is invalid if it is + strictly greater than *max*. + + - __snit::enum__ __validate__ ?*value*? + + - __snit::enum__ *name* ?*option* *value*...? + + Validates that a value comes from an enumerated list. The base type is of + little use by itself, as only subtypes actually have an enumerated list to + validate against. Subtypes may be created with the following options: + + * __-values__ *list* + + Specifies a list of valid values. A value is valid if and only if it's + included in the list. + + - __snit::fpixels__ __validate__ ?*value*? + + - __snit::fpixels__ *name* ?*option* *value*...? + + *Tk programs only.* Validates screen distances, in any of the forms accepted + by __winfo fpixels__. Subtypes may be created with the following options: + + * __-min__ *min* + + Specifies a minimum bound; a value is invalid if it is strictly less + than *min*. The bound may be expressed in any of the forms accepted by + __winfo fpixels__. + + * __-max__ *max* + + Specifies a maximum bound; a value is invalid if it is strictly greater + than *max*. The bound may be expressed in any of the forms accepted by + __winfo fpixels__. + + - __snit::integer__ __validate__ ?*value*? + + - __snit::integer__ *name* ?*option* *value*...? + + Validates integer values. Subtypes may be created with the following + options: + + * __-min__ *min* + + Specifies an integer minimum bound; a value is invalid if it is strictly + less than *min*. + + * __-max__ *max* + + Specifies an integer maximum bound; a value is invalid if it is strictly + greater than *max*. + + - __snit::listtype__ __validate__ ?*value*? + + - __snit::listtype__ *name* ?*option* *value*...? + + Validates Tcl lists. Subtypes may be created with the following options: + + * __-minlen__ *min* + + Specifies a minimum list length; the value is invalid if it has fewer + than *min* elements. Defaults to 0. + + * __-maxlen__ *max* + + Specifies a maximum list length; the value is invalid if it more than + *max* elements. + + * __-type__ *type* + + Specifies the type of the list elements; *type* must be the name of a + validation type or subtype. In the following example, the value of + __-numbers__ must be a list of integers. + + option -numbers -type {snit::listtype -type snit::integer} + + Note that this option doesn't support defining new validation subtypes + on the fly; that is, the following code will not work (yet, anyway): + + option -numbers -type { + snit::listtype -type {snit::integer -min 5} + } + + Instead, define the subtype explicitly: + + snit::integer gt4 -min 5 + + snit::type mytype { + option -numbers -type {snit::listtype -type gt4} + } + + - __snit::pixels__ __validate__ ?*value*? + + - __snit::pixels__ *name* ?*option* *value*...? + + *Tk programs only.* Validates screen distances, in any of the forms accepted + by __winfo pixels__. Subtypes may be created with the following options: + + * __-min__ *min* + + Specifies a minimum bound; a value is invalid if it is strictly less + than *min*. The bound may be expressed in any of the forms accepted by + __winfo pixels__. + + * __-max__ *max* + + Specifies a maximum bound; a value is invalid if it is strictly greater + than *max*. The bound may be expressed in any of the forms accepted by + __winfo pixels__. + + - __snit::stringtype__ __validate__ ?*value*? + + - __snit::stringtype__ *name* ?*option* *value*...? + + Validates Tcl strings. The base type is of little use by itself, since very + Tcl value is also a valid string. Subtypes may be created with the following + options: + + * __-minlen__ *min* + + Specifies a minimum string length; the value is invalid if it has fewer + than *min* characters. Defaults to 0. + + * __-maxlen__ *max* + + Specifies a maximum string length; the value is invalid if it has more + than *max* characters. + + * __-glob__ *pattern* + + Specifies a __string match__ pattern; the value is invalid if it doesn't + match the pattern. + + * __-regexp__ *regexp* + + Specifies a regular expression; the value is invalid if it doesn't match + the regular expression. + + * __-nocase__ *flag* + + By default, both __-glob__ and __-regexp__ matches are case-sensitive. + If __-nocase__ is set to true, then both __-glob__ and __-regexp__ + matches are case-insensitive. + + - __snit::window__ __validate__ ?*value*? + + - __snit::window__ *name* + + *Tk programs only.* Validates Tk window names. The value must cause __winfo + exists__ to return true; otherwise, the value is invalid. It's possible to + define subtypes--that is, instances--of __snit::window__, but as it has no + options at present there's no reason to do so. + +## Defining Validation Types + +There are three ways to define a new validation type: as a subtype of one of +Snit's validation types, as a validation type command, and as a full-fledged +validation type similar to those provided by Snit. Defining subtypes of Snit's +validation types is described above, under [Validation Types](#subsection11). + +The next simplest way to create a new validation type is as a validation type +command. A validation type is simply an object that has a __validate__ method; +the __validate__ method must take one argument, a value, return the value if it +is valid, and throw an error with __-errorcode__ INVALID if the value is +invalid. This can be done with a simple __[proc](../../../../index.md#proc)__. +For example, the __snit::boolean__ validate type could have been implemented +like this: + + proc ::snit::boolean {"validate" value} { + if {![string is boolean -strict $value]} { + return -code error -errorcode INVALID "invalid boolean \"$value\", should be one of: 1, 0, ..." + } + + return $value + } + +A validation type defined in this way cannot be subtyped, of course; but for +many applications this will be sufficient. + +Finally, one can define a full-fledged, subtype-able validation type as a +__snit::type__. Here's a skeleton to get you started: + + snit::type myinteger { + # First, define any options you'd like to use to define + # subtypes. Give them defaults such that they won't take + # effect if they aren't used, and marked them "read-only". + # After all, you shouldn't be changing their values after + # a subtype is defined. + # + # For example: + + option -min -default "" -readonly 1 + option -max -default "" -readonly 1 + + # Next, define a "validate" type method which should do the + # validation in the basic case. This will allow the + # type command to be used as a validation type. + + typemethod validate {value} { + if {![string is integer -strict $value]} { + return -code error -errorcode INVALID "invalid value \"$value\", expected integer" + } + + return $value + } + + # Next, the constructor should validate the subtype options, + # if any. Since they are all readonly, we don't need to worry + # about validating the options on change. + + constructor {args} { + # FIRST, get the options + $self configurelist $args + + # NEXT, validate them. + + # I'll leave this to your imagination. + } + + # Next, define a "validate" instance method; its job is to + # validate values for subtypes. + + method validate {value} { + # First, call the type method to do the basic validation. + $type validate $value + + # Now we know it's a valid integer. + + if {("" != $options(-min) && $value < $options(-min)) || + ("" != $options(-max) && $value > $options(-max))} { + # It's out of range; format a detailed message about + # the error, and throw it. + + set msg "...." + + return -code error -errorcode INVALID $msg + } + + # Otherwise, if it's valid just return it. + return $valid + } + } + +And now you have a type that can be subtyped. + +The file "validate.tcl" in the Snit distribution defines all of Snit's +validation types; you can find the complete implementation for __snit::integer__ +and the other types there, to use as examples for your own types. + +# CAVEATS + +If you have problems, find bugs, or new ideas you are hereby cordially invited +to submit a report of your problem, bug, or idea as explained in the section +[Bugs, Ideas, Feedback](#section8) below. + +Additionally, you might wish to join the Snit mailing list; see +[http://www.wjduquette.com/snit](http://www.wjduquette.com/snit) for details. + +One particular area to watch is using __snit::widgetadaptor__ to adapt +megawidgets created by other megawidget packages; correct widget destruction +depends on the order of the bindings. The wisest course is simply not +to do this. + +# KNOWN BUGS + + - Error stack traces returned by Snit 1.x are extremely ugly and typically + contain far too much information about Snit internals. The error messages + are much improved in Snit 2.2. + + - Also see the Project Trackers as explained in the section [Bugs, Ideas, + Feedback](#section8) below. + +# HISTORY + +During the course of developing Notebook (See +[http://www.wjduquette.com/notebook](http://www.wjduquette.com/notebook)), my +Tcl-based personal notebook application, I found I was writing it as a +collection of objects. I wasn't using any particular object-oriented framework; +I was just writing objects in pure Tcl following the guidelines in my Guide to +Object Commands (see +[http://www.wjduquette.com/tcl/objects.html](http://www.wjduquette.com/tcl/objects.html)), +along with a few other tricks I'd picked up since. And though it was working +well, it quickly became tiresome because of the amount of boilerplate code +associated with each new object type. + +So that was one thing--tedium is a powerful motivator. But the other thing I +noticed is that I wasn't using inheritance at all, and I wasn't missing it. +Instead, I was using delegation: objects that created other objects and +delegated methods to them. + +And I said to myself, "This is getting tedious...there has got to be a better +way." And one afternoon, on a whim, I started working on Snit, an object system +that works the way Tcl works. Snit doesn't support inheritance, but it's great +at delegation, and it makes creating megawidgets easy. + +If you have any comments or suggestions (or bug reports!) don't hesitate to send +me e-mail at [will@wjduquette.com](will@wjduquette.com). In addition, there's a +Snit mailing list; you can find out more about it at the Snit home page (see +[http://www.wjduquette.com/snit](http://www.wjduquette.com/snit)). + +# CREDITS + +Snit has been designed and implemented from the very beginning by William H. +Duquette. However, much credit belongs to the following people for using Snit +and providing me with valuable feedback: Rolf Ade, Colin McCormack, Jose +Nazario, Jeff Godfrey, Maurice Diamanti, Egon Pasztor, David S. Cargo, Tom +Krehbiel, Michael Cleverly, Andreas Kupries, Marty Backe, Andy Goth, Jeff Hobbs, +Brian Griffin, Donal Fellows, Miguel Sofer, Kenneth Green, and Anton Kovalenko. +If I've forgotten anyone, my apologies; let me know and I'll add your name to +the list. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *snit* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[BWidget](../../../../index.md#bwidget), [C++](../../../../index.md#c_), [Incr +Tcl](../../../../index.md#incr_tcl), [Snit](../../../../index.md#snit), +[adaptors](../../../../index.md#adaptors), [class](../../../../index.md#class), +[mega widget](../../../../index.md#mega_widget), +[object](../../../../index.md#object), [object +oriented](../../../../index.md#object_oriented), +[type](../../../../index.md#type), [widget](../../../../index.md#widget), +[widget adaptors](../../../../index.md#widget_adaptors) + +# CATEGORY + +Programming tools + +# COPYRIGHT + +Copyright © 2003-2009, by William H. Duquette ADDED embedded/md/tcllib/files/modules/snit/snitfaq.md Index: embedded/md/tcllib/files/modules/snit/snitfaq.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/snit/snitfaq.md @@ -0,0 +1,3689 @@ + +[//000000001]: # (snitfaq - Snit's Not Incr Tcl, OO system) +[//000000002]: # (Generated from file 'snitfaq.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (snitfaq(n) 2.2 tcllib "Snit's Not Incr Tcl, OO system") + +# NAME + +snitfaq - Snit Frequently Asked Questions + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + + - [OVERVIEW](#section2) + + - [What is this document?](#subsection1) + + - [What is Snit?](#subsection2) + + - [What version of Tcl does Snit require?](#subsection3) + + - [Where can I download Snit?](#subsection4) + + - [What are Snit's goals?](#subsection5) + + - [How is Snit different from other OO frameworks?](#subsection6) + + - [What can I do with Snit?](#subsection7) + + - [SNIT VERSIONS](#section3) + + - [Which version of Snit should I use?](#subsection8) + + - [How do I select the version of Snit I want to use?](#subsection9) + + - [How are Snit 1.3 and Snit 2.2 incompatible?](#subsection10) + + - [Are there other differences between Snit 1.x and Snit + 2.2?](#subsection11) + + - [OBJECTS](#section4) + + - [What is an object?](#subsection12) + + - [What is an abstract data type?](#subsection13) + + - [What kinds of abstract data types does Snit provide?](#subsection14) + + - [What is a snit::type?](#subsection15) + + - [What is a snit::widget?, the short story](#subsection16) + + - [What is a snit::widgetadaptor?, the short story](#subsection17) + + - [How do I create an instance of a snit::type?](#subsection18) + + - [How do I refer to an object indirectly?](#subsection19) + + - [How can I generate the object name automatically?](#subsection20) + + - [Can types be renamed?](#subsection21) + + - [Can objects be renamed?](#subsection22) + + - [How do I destroy a Snit object?](#subsection23) + + - [INSTANCE METHODS](#section5) + + - [What is an instance method?](#subsection24) + + - [How do I define an instance method?](#subsection25) + + - [How does a client call an instance method?](#subsection26) + + - [How does an instance method call another instance + method?](#subsection27) + + - [Are there any limitations on instance method names?](#subsection28) + + - [What is a hierarchical method?](#subsection29) + + - [How do I define a hierarchical method?](#subsection30) + + - [How do I call hierarchical methods?](#subsection31) + + - [How do I make an instance method private?](#subsection32) + + - [Are there any limitations on instance method + arguments?](#subsection33) + + - [What implicit arguments are passed to each instance + method?](#subsection34) + + - [What is $type?](#subsection35) + + - [What is $self?](#subsection36) + + - [What is $selfns?](#subsection37) + + - [What is $win?](#subsection38) + + - [How do I pass an instance method as a callback?](#subsection39) + + - [How do I delegate instance methods to a component?](#subsection40) + + - [INSTANCE VARIABLES](#section6) + + - [What is an instance variable?](#subsection41) + + - [How is a scalar instance variable defined?](#subsection42) + + - [How is an array instance variable defined?](#subsection43) + + - [What happens if I don't initialize an instance + variable?](#subsection44) + + - [Are there any limitations on instance variable names?](#subsection45) + + - [Do I need to declare my instance variables in my + methods?](#subsection46) + + - [How do I pass an instance variable's name to another + object?](#subsection47) + + - [How do I make an instance variable public?](#subsection48) + + - [OPTIONS](#section7) + + - [What is an option?](#subsection49) + + - [How do I define an option?](#subsection50) + + - [How can a client set options at object creation?](#subsection51) + + - [How can a client retrieve an option's value?](#subsection52) + + - [How can a client set options after object creation?](#subsection53) + + - [How should an instance method access an option value?](#subsection54) + + - [How can I make an option read-only?](#subsection55) + + - [How can I catch accesses to an option's value?](#subsection56) + + - [What is a -cgetmethod?](#subsection57) + + - [How can I catch changes to an option's value?](#subsection58) + + - [What is a -configuremethod?](#subsection59) + + - [How can I validate an option's value?](#subsection60) + + - [What is a -validatemethod?](#subsection61) + + - [TYPE VARIABLES](#section8) + + - [What is a type variable?](#subsection62) + + - [How is a scalar type variable defined?](#subsection63) + + - [How is an array-valued type variable defined?](#subsection64) + + - [What happens if I don't initialize a type variable?](#subsection65) + + - [Are there any limitations on type variable names?](#subsection66) + + - [Do I need to declare my type variables in my methods?](#subsection67) + + - [How do I pass a type variable's name to another + object?](#subsection68) + + - [How do I make a type variable public?](#subsection69) + + - [TYPE METHODS](#section9) + + - [What is a type method?](#subsection70) + + - [How do I define a type method?](#subsection71) + + - [How does a client call a type method?](#subsection72) + + - [Are there any limitations on type method names?](#subsection73) + + - [How do I make a type method private?](#subsection74) + + - [Are there any limitations on type method arguments?](#subsection75) + + - [How does an instance or type method call a type + method?](#subsection76) + + - [How do I pass a type method as a callback?](#subsection77) + + - [Can type methods be hierarchical?](#subsection78) + + - [PROCS](#section10) + + - [What is a proc?](#subsection79) + + - [How do I define a proc?](#subsection80) + + - [Are there any limitations on proc names?](#subsection81) + + - [How does a method call a proc?](#subsection82) + + - [How can I pass a proc to another object as a callback?](#subsection83) + + - [TYPE CONSTRUCTORS](#section11) + + - [What is a type constructor?](#subsection84) + + - [How do I define a type constructor?](#subsection85) + + - [CONSTRUCTORS](#section12) + + - [What is a constructor?](#subsection86) + + - [How do I define a constructor?](#subsection87) + + - [What does the default constructor do?](#subsection88) + + - [Can I choose a different set of arguments for the + constructor?](#subsection89) + + - [Are there any limitations on constructor arguments?](#subsection90) + + - [Is there anything special about writing the + constructor?](#subsection91) + + - [DESTRUCTORS](#section13) + + - [What is a destructor?](#subsection92) + + - [How do I define a destructor?](#subsection93) + + - [Are there any limitations on destructor arguments?](#subsection94) + + - [What implicit arguments are passed to the destructor?](#subsection95) + + - [Must components be destroyed explicitly?](#subsection96) + + - [Is there any special about writing a destructor?](#subsection97) + + - [COMPONENTS](#section14) + + - [What is a component?](#subsection98) + + - [How do I declare a component?](#subsection99) + + - [How is a component named?](#subsection100) + + - [Are there any limitations on component names?](#subsection101) + + - [What is an owned component?](#subsection102) + + - [What does the install command do?](#subsection103) + + - [Must owned components be created in the constructor?](#subsection104) + + - [Are there any limitations on component object names?](#subsection105) + + - [Must I destroy the components I own?](#subsection106) + + - [Can I expose a component's object command as part of my + interface?](#subsection107) + + - [How do I expose a component's object command?](#subsection108) + + - [TYPE COMPONENTS](#section15) + + - [What is a type component?](#subsection109) + + - [How do I declare a type component?](#subsection110) + + - [How do I install a type component?](#subsection111) + + - [Are there any limitations on type component names?](#subsection112) + + - [DELEGATION](#section16) + + - [What is delegation?](#subsection113) + + - [How can I delegate a method to a component object?](#subsection114) + + - [Can I delegate to a method with a different name?](#subsection115) + + - [Can I delegate to a method with additional arguments?](#subsection116) + + - [Can I delegate a method to something other than an + object?](#subsection117) + + - [How can I delegate a method to a type component + object?](#subsection118) + + - [How can I delegate a type method to a type component + object?](#subsection119) + + - [How can I delegate an option to a component object?](#subsection120) + + - [Can I delegate to an option with a different name?](#subsection121) + + - [How can I delegate any unrecognized method or option to a component + object?](#subsection122) + + - [How can I delegate all but certain methods or options to a + component?](#subsection123) + + - [Can a hierarchical method be delegated?](#subsection124) + + - [WIDGETS](#section17) + + - [What is a snit::widget?](#subsection125) + + - [How do I define a snit::widget?](#subsection126) + + - [How do snit::widgets differ from snit::types?](#subsection127) + + - [What is a hull component?](#subsection128) + + - [How can I set the hull type for a snit::widget?](#subsection129) + + - [How should I name widgets which are components of a + snit::widget?](#subsection130) + + - [WIDGET ADAPTORS](#section18) + + - [What is a snit::widgetadaptor?](#subsection131) + + - [How do I define a snit::widgetadaptor?](#subsection132) + + - [Can I adapt a widget created elsewhere in the + program?](#subsection133) + + - [Can I adapt another megawidget?](#subsection134) + + - [THE TK OPTION DATABASE](#section19) + + - [What is the Tk option database?](#subsection135) + + - [Do snit::types use the Tk option database?](#subsection136) + + - [What is my snit::widget's widget class?](#subsection137) + + - [What is my snit::widgetadaptor's widget class?](#subsection138) + + - [What are option resource and class names?](#subsection139) + + - [What are the resource and class names for my megawidget's + options?](#subsection140) + + - [How does Snit initialize my megawidget's locally-defined + options?](#subsection141) + + - [How does Snit initialize delegated options?](#subsection142) + + - [How does Snit initialize options delegated to the + hull?](#subsection143) + + - [How does Snit initialize options delegated to other + components?](#subsection144) + + - [What happens if I install a non-widget as a component of + widget?](#subsection145) + + - [ENSEMBLE COMMANDS](#section20) + + - [What is an ensemble command?](#subsection146) + + - [How can I create an ensemble command using Snit?](#subsection147) + + - [How can I create an ensemble command using an instance of a + snit::type?](#subsection148) + + - [How can I create an ensemble command using a + snit::type?](#subsection149) + + - [PRAGMAS](#section21) + + - [What is a pragma?](#subsection150) + + - [How do I set a pragma?](#subsection151) + + - [How can I get rid of the "info" type method?](#subsection152) + + - [How can I get rid of the "destroy" type method?](#subsection153) + + - [How can I get rid of the "create" type method?](#subsection154) + + - [How can I get rid of type methods altogether?](#subsection155) + + - [Why can't I create an object that replaces an old object with the same + name?](#subsection156) + + - [How can I make my simple type run faster?](#subsection157) + + - [MACROS](#section22) + + - [What is a macro?](#subsection158) + + - [What are macros good for?](#subsection159) + + - [How do I do conditional compilation?](#subsection160) + + - [How do I define new type definition syntax?](#subsection161) + + - [Are there are restrictions on macro names?](#subsection162) + + - [Bugs, Ideas, Feedback](#section23) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# DESCRIPTION + +# OVERVIEW + +## What is this document? + +This is an atypical FAQ list, in that few of the questions are frequently asked. +Rather, these are the questions I think a newcomer to Snit should be asking. +This file is not a complete reference to Snit, however; that information is in +the __[snit](snit.md)__ man page. + +## What is Snit? + +Snit is a framework for defining abstract data types and megawidgets in pure +Tcl. The name "Snit" stands for "Snit's Not Incr Tcl", signifying that Snit +takes a different approach to defining objects than does Incr Tcl, the best +known object framework for Tcl. Had I realized that Snit would become at all +popular, I'd probably have chosen something else. + +The primary purpose of Snit is to be *object glue*--to help you compose diverse +objects from diverse sources into types and megawidgets with clean, convenient +interfaces so that you can more easily build your application. + +Snit isn't about theoretical purity or minimalist design; it's about being able +to do powerful things easily and consistently without having to think about +them--so that you can concentrate on building your application. + +Snit isn't about implementing thousands of nearly identical carefully-specified +lightweight thingamajigs--not as individual Snit objects. Traditional Tcl +methods will be much faster, and not much more complicated. But Snit *is* about +implementing a clean interface to manage a collection of thousands of nearly +identical carefully-specified lightweight thingamajigs (e.g., think of the text +widget and text tags, or the canvas widget and canvas objects). Snit lets you +hide the details of just how those thingamajigs are stored--so that you can +ignore it, and concentrate on building your application. + +Snit isn't a way of life, a silver bullet, or the Fountain of Youth. It's just a +way of managing complexity--and of managing some of the complexity of managing +complexity--so that you can concentrate on building your application. + +## What version of Tcl does Snit require? + +Snit 1.3 requires Tcl 8.3 or later; Snit 2.2 requires Tcl 8.5 or later. See +[SNIT VERSIONS](#section3) for the differences between Snit 1.3 and Snit 2.2. + +## Where can I download Snit? + +Snit is part of Tcllib, the standard Tcl library, so you might already have it. +It's also available at the Snit Home Page, +[http://www.wjduquette.com/snit](http://www.wjduquette.com/snit). + +## What are Snit's goals? + + - A Snit object should be at least as efficient as a hand-coded Tcl object + (see + [http://www.wjduquette.com/tcl/objects.html](http://www.wjduquette.com/tcl/objects.html)). + + - The fact that Snit was used in an object's implementation should be + transparent (and irrelevant) to clients of that object. + + - Snit should be able to encapsulate objects from other sources, particularly + Tk widgets. + + - Snit megawidgets should be (to the extent possible) indistinguishable in + interface from Tk widgets. + + - Snit should be Tclish--that is, rather than trying to emulate C++, + Smalltalk, or anything else, it should try to emulate Tcl itself. + + - It should have a simple, easy-to-use, easy-to-remember syntax. + +## How is Snit different from other OO frameworks? + +Snit is unique among Tcl object systems in that it is based not on inheritance +but on delegation. Object systems based on inheritance only allow you to inherit +from classes defined using the same system, and that's a shame. In Tcl, an +object is anything that acts like an object; it shouldn't matter how the object +was implemented. I designed Snit to help me build applications out of the +materials at hand; thus, Snit is designed to be able to incorporate and build on +any object, whether it's a hand-coded object, a Tk widget, an Incr Tcl object, a +BWidget or almost anything else. + +Note that you can achieve the effect of inheritance using +[COMPONENTS](#section14) and [DELEGATION](#section16)--and you can inherit from +anything that looks like a Tcl object. + +## What can I do with Snit? + +Using Snit, a programmer can: + + - Create abstract data types and Tk megawidgets. + + - Define instance variables, type variables, and Tk-style options. + + - Define constructors, destructors, instance methods, type methods, procs. + + - Assemble a type out of component types. Instance methods and options can be + delegated to the component types automatically. + +# SNIT VERSIONS + +## Which version of Snit should I use? + +The current Snit distribution includes two versions, Snit 1.3 and Snit 2.2. The +reason that both are included is that Snit 2.2 takes advantage of a number of +new features of Tcl 8.5 to improve run-time efficiency; as a side-effect, the +ugliness of Snit's error messages and stack traces has been reduced +considerably. The cost of using Snit 2.2, of course, is that you must target Tcl +8.5. + +Snit 1.3, on the other hand, lacks Snit 2.2's optimizations, but requires only +Tcl 8.3 and later. + +In short, if you're targetting Tcl 8.3 or 8.4 you should use Snit 1.3. If you +can afford to target Tcl 8.5, you should definitely use Snit 2.2. If you will be +targetting both, you can use Snit 1.3 exclusively, or (if your code is +unaffected by the minor incompatibilities between the two versions) you can use +Snit 1.3 for Tcl 8.4 and Snit 2.2 for Tcl 8.5. + +## How do I select the version of Snit I want to use? + +To always use Snit 1.3 (or a later version of Snit 1.x), invoke Snit as follows: + + package require snit 1.3 + +To always use Snit 2.2 (or a later version of Snit 2.x), say this instead: + + package require snit 2.2 + +Note that if you request Snit 2.2 explicitly, your application will halt with +Tcl 8.4, since Snit 2.2 is unavailable for Tcl 8.4. + +If you wish your application to always use the latest available version of Snit, +don't specify a version number: + + package require snit + +Tcl will find and load the latest version that's available relative to the +version of Tcl being used. In this case, be careful to avoid using any +incompatible features. + +## How are Snit 1.3 and Snit 2.2 incompatible? + +To the extent possible, Snit 2.2 is intended to be a drop-in replacement for +Snit 1.3. Unfortunately, some incompatibilities were inevitable because Snit 2.2 +uses Tcl 8.5's new __namespace ensemble__ mechanism to implement subcommand +dispatch. This approach is much faster than the mechanism used in Snit 1.3, and +also results in much better error messages; however, it also places new +constraints on the implementation. + +There are four specific incompatibilities between Snit 1.3 and Snit 2.2. + + - Snit 1.3 supports implicit naming of objects. Suppose you define a new + __snit::type__ called __dog__. You can create instances of __dog__ in three + ways: + + dog spot ;# Explicit naming + set obj1 [dog %AUTO%] ;# Automatic naming + set obj2 [dog] ;# Implicit naming + + In Snit 2.2, type commands are defined using the __namespace ensemble__ + mechanism; and __namespace ensemble__ doesn't allow an ensemble command to + be called without a subcommand. In short, using __namespace ensemble__ + there's no way to support implicit naming. + + All is not lost, however. If the type has no type methods, then the type + command is a simple command rather than an ensemble, and __namespace + ensemble__ is not used. In this case, implicit naming is still possible. + + In short, you can have implicit naming if you're willing to do without type + methods (including the standard type methods, like __$type info__). To do + so, use the __-hastypemethods__ pragma: + + pragma -hastypemethods 0 + + - Hierarchical methods and type methods are implemented differently in Snit + 2.2. + + A hierarchical method is an instance method which has subcommands; these + subcommands are themselves methods. The Tk text widget's __tag__ command and + its subcommands are examples of hierarchical methods. You can implement such + subcommands in Snit simply by including multiple words in the method names: + + method {tag configure} {tag args} { ... } + + method {tag cget} {tag option} {...} + + Here we've implicitly defined a __tag__ method which has two subcommands, + __configure__ and __cget__. + + In Snit 1.3, hierarchical methods could be called in two ways: + + $obj tag cget -myoption ;# The good way + $obj {tag cget} -myoption ;# The weird way + + In the second call, we see that a hierarchical method or type method is + simply one whose name contains multiple words. + + In Snit 2.2 this is no longer the case, and the "weird" way of calling + hierarchical methods and type methods no longer works. + + - The third incompatibility derives from the second. In Snit 1.3, hierarchical + methods were also simply methods whose name contains multiple words. As a + result, __$obj info methods__ returned the full names of all hierarchical + methods. In the example above, the list returned by __$obj info methods__ + would include __tag configure__ and __tag cget__ but not __tag__, since + __tag__ is defined only implicitly. + + In Snit 2.2, hierarchical methods and type methods are no longer simply ones + whose name contains multiple words; in the above example, the list returned + by __$obj info methods__ would include __tag__ but not __tag configure__ or + __tag cget__. + + - The fourth incompatibility is due to a new feature. Snit 2.2 uses the new + __namespace path__ command so that a type's code can call any command + defined in the type's parent namespace without qualification or importation. + For example, suppose you have a package called __mypackage__ which defines a + number of commands including a type, __::mypackage::mytype__. Thanks to + __namespace path__, the type's code can call any of the other commands + defined in __::mypackage::__. + + This is extremely convenient. However, it also means that commands defined + in the parent namespace, __::mypackage::__ can block the type's access to + identically named commands in the global namespace. This can lead to bugs. + For example, Tcllib includes a type called __::tie::std::file__. This type's + code calls the standard __[file](../../../../index.md#file)__ command. When + run with Snit 2.2, the code broke-- the type's command, + __::tie::std::file__, is itself a command in the type's parent namespace, + and so instead of calling the standard __[file](../../../../index.md#file)__ + command, the type found itself calling itself. + +## Are there other differences between Snit 1.x and Snit 2.2? + +Yes. + + - Method dispatch is considerably faster. + + - Many error messages and stack traces are cleaner. + + - The __-simpledispatch__ pragma is obsolete, and ignored if present. In Snit + 1.x, __-simpledispatch__ substitutes a faster mechanism for method dispatch, + at the cost of losing certain features. Snit 2.2 method dispatch is faster + still in all cases, so __-simpledispatch__ is no longer needed. + + - In Snit 2.2, a type's code (methods, type methods, etc.) can call commands + from the type's parent namespace without qualifying or importing them, i.e., + type __::parentns::mytype__'s code can call __::parentns::someproc__ as just + __someproc__. + + This is extremely useful when a type is defined as part of a larger package, + and shares a parent namespace with the rest of the package; it means that + the type can call other commands defined by the package without any extra + work. + + This feature depends on the new Tcl 8.5 __namespace path__ command, which is + why it hasn't been implemented for V1.x. V1.x code can achieve something + similar by placing + + namespace import [namespace parent]::* + + in a type constructor. This is less useful, however, as it picks up only + those commands which have already been exported by the parent namespace at + the time the type is defined. + +# OBJECTS + +## What is an object? + +A full description of object-oriented programming is beyond the scope of this +FAQ, obviously. In simple terms, an object is an instance of an abstract data +type--a coherent bundle of code and data. There are many ways to represent +objects in Tcl/Tk; the best known examples are the Tk widgets. + +A Tk widget is an object; it is represented by a Tcl command. The object's +methods are subcommands of the Tcl command. The object's properties are options +accessed using the __configure__ and __cget__ methods. Snit uses the same +conventions as Tk widgets do. + +## What is an abstract data type? + +In computer science terms, an abstract data type is a complex data structure +along with a set of operations--a stack, a queue, a binary tree, etc--that is to +say, in modern terms, an object. In systems that include some form of +inheritance the word *[class](../../../../index.md#class)* is usually used +instead of *abstract data type*, but as Snit doesn't implement inheritance as +it's ordinarily understood the older term seems more appropriate. Sometimes this +is called *object-based* programming as opposed to object-oriented programming. +Note that you can easily create the effect of inheritance using +[COMPONENTS](#section14) and [DELEGATION](#section16). + +In Snit, as in Tk, a *[type](../../../../index.md#type)* is a command that +creates instances -- objects -- which belong to the type. Most types define some +number of *options* which can be set at creation time, and usually can be +changed later. + +Further, an *instance* is also a Tcl command--a command that gives access to the +operations which are defined for that abstract data type. Conventionally, the +operations are defined as subcommands of the instance command. For example, to +insert text into a Tk text widget, you use the text widget's __insert__ +subcommand: + + # Create a text widget and insert some text in it. + text .mytext -width 80 -height 24 + .mytext insert end "Howdy!" + +In this example, __[text](../../../../index.md#text)__ is the +*[type](../../../../index.md#type)* command and __.mytext__ is the *instance* +command. + +In Snit, object subcommands are generally called [INSTANCE METHODS](#section5). + +## What kinds of abstract data types does Snit provide? + +Snit allows you to define three kinds of abstract data type: + + - __snit::type__ + + - __snit::widget__ + + - __snit::widgetadaptor__ + +## What is a snit::type? + +A __snit::type__ is a non-GUI abstract data type, e.g., a stack or a queue. +__snit::type__s are defined using the __snit::type__ command. For example, if +you were designing a kennel management system for a dog breeder, you'd need a +dog type. + + % snit::type dog { + # ... + } + ::dog + % + +This definition defines a new command (__::dog__, in this case) that can be used +to define dog objects. + +An instance of a __snit::type__ can have [INSTANCE METHODS](#section5), +[INSTANCE VARIABLES](#section6), [OPTIONS](#section7), and +[COMPONENTS](#section14). The type itself can have [TYPE METHODS](#section9), +[TYPE VARIABLES](#section8), [TYPE COMPONENTS](#section15), and +[PROCS](#section10). + +## What is a snit::widget?, the short story + +A __snit::widget__ is a Tk megawidget built using Snit; it is very similar to a +__snit::type__. See [WIDGETS](#section17). + +## What is a snit::widgetadaptor?, the short story + +A __snit::widgetadaptor__ uses Snit to wrap an existing widget type (e.g., a Tk +label), modifying its interface to a lesser or greater extent. It is very +similar to a __snit::widget__. See [WIDGET ADAPTORS](#section18). + +## How do I create an instance of a snit::type? + +You create an instance of a __snit::type__ by passing the new instance's name to +the type's create method. In the following example, we create a __dog__ object +called __spot__. + + % snit::type dog { + # .... + } + ::dog + % dog create spot + ::spot + % + +In general, the __create__ method name can be omitted so long as the instance +name doesn't conflict with any defined [TYPE METHODS](#section9). (See [TYPE +COMPONENTS](#section15) for the special case in which this doesn't work.) So the +following example is identical to the previous example: + + % snit::type dog { + # .... + } + ::dog + % dog spot + ::spot + % + +This document generally uses the shorter form. + +If the __dog__ type defines [OPTIONS](#section7), these can usually be given +defaults at creation time: + + % snit::type dog { + option -breed mongrel + option -color brown + + method bark {} { return "$self barks." } + } + ::dog + % dog create spot -breed dalmation -color spotted + ::spot + % spot cget -breed + dalmation + % spot cget -color + spotted + % + +Once created, the instance name now names a new Tcl command that is used to +manipulate the object. For example, the following code makes the dog bark: + + % spot bark + ::spot barks. + % + +## How do I refer to an object indirectly? + +Some programmers prefer to save the object name in a variable, and reference it +that way. For example, + + % snit::type dog { ... } + ::dog + % set d [dog spot -breed dalmation -color spotted] + ::spot + % $d cget -breed + dalmation + % $d bark + ::spot barks. + % + +If you prefer this style, you might prefer to have Snit generate the instance's +name automatically. + +## How can I generate the object name automatically? + +If you'd like Snit to generate an object name for you, use the __%AUTO%__ +keyword as the requested name: + + % snit::type dog { ... } + ::dog + % set d [dog %AUTO%] + ::dog2 + % $d bark + ::dog2 barks. + % + +The __%AUTO%__ keyword can be embedded in a longer string: + + % set d [dog obj_%AUTO%] + ::obj_dog4 + % $d bark + ::obj_dog4 barks. + % + +## Can types be renamed? + +Tcl's __rename__ command renames other commands. It's a common technique in Tcl +to modify an existing command by renaming it and defining a new command with the +original name; the new command usually calls the renamed command. + +__snit::type__ commands, however, should never be renamed; to do so breaks the +connection between the type and its objects. + +## Can objects be renamed? + +Tcl's __rename__ command renames other commands. It's a common technique in Tcl +to modify an existing command by renaming it and defining a new command with the +original name; the new command usually calls the renamed command. + +All Snit objects (including *widgets* and *widgetadaptors*) can be renamed, +though this flexibility has some consequences: + + - In an instance method, the implicit argument __self__ will always contain + the object's current name, so instance methods can always call other + instance methods using __$self__. + + - If the object is renamed, however, then __$self__'s value will change. + Therefore, don't use __$self__ for anything that will break if __$self__ + changes. For example, don't pass a callback command to another object like + this: + + .btn configure -command [list $self ButtonPress] + + You'll get an error if __.btn__ calls your command after your object is + renamed. + + - Instead, your object should define its callback command like this: + + .btn configure -command [mymethod ButtonPress] + + The __mymethod__ command returns code that will call the desired method + safely; the caller of the callback can add additional arguments to the end + of the command as usual. + + - Every object has a private namespace; the name of this namespace is + available in method bodies, etc., as the value of the implicit argument + __selfns__. This value is constant for the life of the object. Use + __$selfns__ instead of __$self__ if you need a unique token to identify the + object. + + - When a __snit::widget__'s instance command is renamed, its Tk window name + remains the same -- and is still extremely important. Consequently, the Tk + window name is available in method bodies as the value of the implicit + argument __win__. This value is constant for the life of the object. When + creating child windows, it's best to use __$win.child__ rather than + __$self.child__ as the name of the child window. + +## How do I destroy a Snit object? + +Any Snit object of any type can be destroyed by renaming it to the empty string +using the Tcl __rename__ command. + +Snit megawidgets (i.e., instances of __snit::widget__ and +__snit::widgetadaptor__) can be destroyed like any other widget: by using the Tk +__destroy__ command on the widget or on one of its ancestors in the window +hierarchy. + +Every instance of a __snit::type__ has a __destroy__ method: + + % snit::type dog { ... } + ::dog + % dog spot + ::spot + % spot bark + ::spot barks. + % spot destroy + % spot barks + invalid command name "spot" + % + +Finally, every Snit type has a type method called __destroy__; calling it +destroys the type and all of its instances: + + % snit::type dog { ... } + ::dog + % dog spot + ::spot + % spot bark + ::spot barks. + % dog destroy + % spot bark + invalid command name "spot" + % dog fido + invalid command name "dog" + % + +# INSTANCE METHODS + +## What is an instance method? + +An instance method is a procedure associated with a specific object and called +as a subcommand of the object's command. It is given free access to all of the +object's type variables, instance variables, and so forth. + +## How do I define an instance method? + +Instance methods are defined in the type definition using the +__[method](../../../../index.md#method)__ statement. Consider the following code +that might be used to add dogs to a computer simulation: + + % snit::type dog { + method bark {} { + return "$self barks." + } + + method chase {thing} { + return "$self chases $thing." + } + } + ::dog + % + +A dog can bark, and it can chase things. + +The __[method](../../../../index.md#method)__ statement looks just like a normal +Tcl __[proc](../../../../index.md#proc)__, except that it appears in a +__snit::type__ definition. Notice that every instance method gets an implicit +argument called __self__; this argument contains the object's name. (There's +more on implicit method arguments below.) + +## How does a client call an instance method? + +The method name becomes a subcommand of the object. For example, let's put a +simulated dog through its paces: + + % dog spot + ::spot + % spot bark + ::spot barks. + % spot chase cat + ::spot chases cat. + % + +## How does an instance method call another instance method? + +If method A needs to call method B on the same object, it does so just as a +client does: it calls method B as a subcommand of the object itself, using the +object name stored in the implicit argument __self__. + +Suppose, for example, that our dogs never chase anything without barking at +them: + + % snit::type dog { + method bark {} { + return "$self barks." + } + + method chase {thing} { + return "$self chases $thing. [$self bark]" + } + } + ::dog + % dog spot + ::spot + % spot bark + ::spot barks. + % spot chase cat + ::spot chases cat. ::spot barks. + % + +## Are there any limitations on instance method names? + +Not really, so long as you avoid the standard instance method names: +__configure__, __configurelist__, __cget__, __destroy__, and __info__. Also, +method names consisting of multiple words define hierarchical methods. + +## What is a hierarchical method? + +An object's methods are subcommands of the object's instance command. +Hierarchical methods allow an object's methods to have subcommands of their own; +and these can in turn have subcommands, and so on. This allows the programmer to +define a tree-shaped command structure, such as is used by many of the Tk +widgets--the subcommands of the Tk __[text](../../../../index.md#text)__ +widget's __tag__ method are hierarchical methods. + +## How do I define a hierarchical method? + +Define methods whose names consist of multiple words. These words define the +hierarchy implicitly. For example, the following code defines a __tag__ method +with subcommands __cget__ and __configure__: + + snit::widget mytext { + method {tag configure} {tag args} { ... } + + method {tag cget} {tag option} {...} + } + +Note that there is no explicit definition for the __tag__ method; it is implicit +in the definition of __tag configure__ and __tag cget__. If you tried to define +__tag__ explicitly in this example, you'd get an error. + +## How do I call hierarchical methods? + +As subcommands of subcommands. + + % mytext .text + .text + % .text tag configure redtext -foreground red -background black + % .text tag cget redtext -foreground + red + % + +## How do I make an instance method private? + +It's often useful to define private methods, that is, instance methods intended +to be called only by other methods of the same object. + +Snit doesn't implement any access control on instance methods, so all methods +are *de facto* public. Conventionally, though, the names of public methods begin +with a lower-case letter, and the names of private methods begin with an +upper-case letter. + +For example, suppose our simulated dogs only bark in response to other stimuli; +they never bark just for fun. So the __bark__ method becomes __Bark__ to +indicate that it is private: + + % snit::type dog { + # Private by convention: begins with uppercase letter. + method Bark {} { + return "$self barks." + } + + method chase {thing} { + return "$self chases $thing. [$self Bark]" + } + } + ::dog + % dog fido + ::fido + % fido chase cat + ::fido chases cat. ::fido barks. + % + +## Are there any limitations on instance method arguments? + +Method argument lists are defined just like normal Tcl +__[proc](../../../../index.md#proc)__ argument lists; in particular, they can +include arguments with default values and the __args__ argument. + +However, every method also has a number of implicit arguments provided by Snit +in addition to those explicitly defined. The names of these implicit arguments +may not used to name explicit arguments. + +## What implicit arguments are passed to each instance method? + +The arguments implicitly passed to every method are __type__, __selfns__, +__win__, and __self__. + +## What is $type? + +The implicit argument __type__ contains the fully qualified name of the object's +type: + + % snit::type thing { + method mytype {} { + return $type + } + } + ::thing + % thing something + ::something + % something mytype + ::thing + % + +## What is $self? + +The implicit argument __self__ contains the object's fully qualified name. + +If the object's command is renamed, then __$self__ will change to match in +subsequent calls. Thus, your code should not assume that __$self__ is constant +unless you know for sure that the object will never be renamed. + + % snit::type thing { + method myself {} { + return $self + } + } + ::thing + % thing mutt + ::mutt + % mutt myself + ::mutt + % rename mutt jeff + % jeff myself + ::jeff + % + +## What is $selfns? + +Each Snit object has a private namespace in which to store its [INSTANCE +VARIABLES](#section6) and [OPTIONS](#section7). The implicit argument __selfns__ +contains the name of this namespace; its value never changes, and is constant +for the life of the object, even if the object's name changes: + + % snit::type thing { + method myNameSpace {} { + return $selfns + } + } + ::thing + % thing jeff + ::jeff + % jeff myNameSpace + ::thing::Snit_inst3 + % rename jeff mutt + % mutt myNameSpace + ::thing::Snit_inst3 + % + +The above example reveals how Snit names an instance's private namespace; +however, you should not write code that depends on the specific naming +convention, as it might change in future releases. + +## What is $win? + +The implicit argument __win__ is defined for all Snit methods, though it really +makes sense only for those of [WIDGETS](#section17) and [WIDGET +ADAPTORS](#section18). __$win__ is simply the original name of the object, +whether it's been renamed or not. For widgets and widgetadaptors, it is also +therefore the name of a Tk window. + +When a __snit::widgetadaptor__ is used to modify the interface of a widget or +megawidget, it must rename the widget's original command and replace it with its +own. + +Thus, using __win__ whenever the Tk window name is called for means that a +__snit::widget__ or __snit::widgetadaptor__ can be adapted by a +__snit::widgetadaptor__. See [WIDGETS](#section17) for more information. + +## How do I pass an instance method as a callback? + +It depends on the context. + +Suppose in my application I have a __dog__ object named __fido__, and I want +__fido__ to bark when a Tk button called __.bark__ is pressed. In this case, I +create the callback command in the usual way, using +__[list](../../../../index.md#list)__: + + button .bark -text "Bark!" -command [list fido bark] + +In typical Tcl style, we use a callback to hook two independent components +together. But suppose that the __dog__ object has a graphical interface and owns +the button itself? In this case, the __dog__ must pass one of its own instance +methods to the button it owns. The obvious thing to do is this: + + % snit::widget dog { + constructor {args} { + #... + button $win.barkbtn -text "Bark!" -command [list $self bark] + #... + } + } + ::dog + % + +(Note that in this example, our __dog__ becomes a __snit::widget__, because it +has GUI behavior. See [WIDGETS](#section17) for more.) Thus, if we create a +__dog__ called __.spot__, it will create a Tk button called __.spot.barkbtn__; +when pressed, the button will call __$self bark__. + +Now, this will work--provided that __.spot__ is never renamed to something else. +But surely renaming widgets is abnormal? And so it is--unless __.spot__ is the +hull component of a __snit::widgetadaptor__. If it is, then it will be renamed, +and __.spot__ will become the name of the __snit::widgetadaptor__ object. When +the button is pressed, the command __$self bark__ will be handled by the +__snit::widgetadaptor__, which might or might not do the right thing. + +There's a safer way to do it, and it looks like this: + + % snit::widget dog { + constructor {args} { + #... + button $win.barkbtn -text "Bark!" -command [mymethod bark] + #... + } + } + ::dog + % + +The command __mymethod__ takes any number of arguments, and can be used like +__[list](../../../../index.md#list)__ to build up a callback command; the only +difference is that __mymethod__ returns a form of the command that won't change +even if the instance's name changes. + +On the other hand, you might prefer to allow a widgetadaptor to override a +method such that your renamed widget will call the widgetadaptor's method +instead of its own. In this case, using __[list $self bark]__ will do what you +want...but this is a technique which should be used only in carefully controlled +circumstances. + +## How do I delegate instance methods to a component? + +See [DELEGATION](#section16). + +# INSTANCE VARIABLES + +## What is an instance variable? + +An instance variable is a private variable associated with some particular Snit +object. Instance variables can be scalars or arrays. + +## How is a scalar instance variable defined? + +Scalar instance variables are defined in the type definition using the +__variable__ statement. You can simply name it, or you can initialize it with a +value: + + snit::type mytype { + # Define variable "greeting" and initialize it with "Howdy!" + variable greeting "Howdy!" + } + +## How is an array instance variable defined? + +Array instance variables are also defined in the type definition using the +__variable__ command. You can initialize them at the same time by specifying the +__-array__ option: + + snit::type mytype { + # Define array variable "greetings" + variable greetings -array { + formal "Good Evening" + casual "Howdy!" + } + } + +## What happens if I don't initialize an instance variable? + +Variables do not really exist until they are given values. If you do not +initialize a variable when you define it, then you must be sure to assign a +value to it (in the constructor, say, or in some method) before you reference +it. + +## Are there any limitations on instance variable names? + +Just a few. + +First, every Snit object has a built-in instance variable called __options__, +which should never be redefined. + +Second, all names beginning with "Snit_" are reserved for use by Snit internal +code. + +Third, instance variable names containing the namespace delimiter (__::__) are +likely to cause great confusion. + +## Do I need to declare my instance variables in my methods? + +No. Once you've defined an instance variable in the type definition, it can be +used in any instance code (instance methods, the constructor, and the +destructor) without declaration. This differs from normal Tcl practice, in which +all non-local variables in a proc need to be declared. + +There is a speed penalty to having all instance variables implicitly available +in all instance code. Even though your code need not declare the variables +explicitly, Snit must still declare them, and that takes time. If you have ten +instance variables, a method that uses none of them must still pay the +declaration penalty for all ten. In most cases, the additional runtime cost is +negligible. If extreme cases, you might wish to avoid it; there are two methods +for doing so. + +The first is to define a single instance variable, an array, and store all of +your instance data in the array. This way, you're only paying the declaration +penalty for one variable--and you probably need the variable most of the time +anyway. This method breaks down if your instance variables include multiple +arrays; in Tcl 8.5, however, the __[dict](../../../../index.md#dict)__ command +might come to your rescue. + +The second method is to declare your instance variables explicitly in your +instance code, while *not* including them in the type definition: + + snit::type dog { + constructor {} { + variable mood + + set mood happy + } + + method setmood {newMood} { + variable mood + + set mood $newMood + } + + method getmood {} { + variable mood + + return $mood + } + } + +This allows you to ensure that only the required variables are included in each +method, at the cost of longer code and run-time errors when you forget to +declare a variable you need. + +## How do I pass an instance variable's name to another object? + +In Tk, it's common to pass a widget a variable name; for example, Tk label +widgets have a __-textvariable__ option which names the variable which will +contain the widget's text. This allows the program to update the label's value +just by assigning a new value to the variable. + +If you naively pass the instance variable name to the label widget, you'll be +confused by the result; Tk will assume that the name names a global variable. +Instead, you need to provide a fully-qualified variable name. From within an +instance method or a constructor, you can fully qualify the variable's name +using the __myvar__ command: + + snit::widget mywidget { + variable labeltext "" + + constructor {args} { + # ... + + label $win.label -textvariable [myvar labeltext] + + # ... + } + } + +## How do I make an instance variable public? + +Practically speaking, you don't. Instead, you'll implement public variables as +[OPTIONS](#section7). Alternatively, you can write [INSTANCE METHODS](#section5) +to set and get the variable's value. + +# OPTIONS + +## What is an option? + +A type's options are the equivalent of what other object-oriented languages +would call public member variables or properties: they are data values which can +be retrieved and (usually) set by the clients of an object. + +Snit's implementation of options follows the Tk model fairly exactly, except +that __snit::type__ objects usually don't interact with [THE TK OPTION +DATABASE](#section19); __snit::widget__ and __snit::widgetadaptor__ objects, on +the other hand, always do. + +## How do I define an option? + +Options are defined in the type definition using the __option__ statement. +Consider the following type, to be used in an application that manages a list of +dogs for a pet store: + + snit::type dog { + option -breed -default mongrel + option -color -default brown + option -akc -default 0 + option -shots -default 0 + } + +According to this, a dog has four notable properties: a breed, a color, a flag +that says whether it's pedigreed with the American Kennel Club, and another flag +that says whether it has had its shots. The default dog, evidently, is a brown +mutt. + +There are a number of options you can specify when defining an option; if +__-default__ is the only one, you can omit the word __-default__ as follows: + + snit::type dog { + option -breed mongrel + option -color brown + option -akc 0 + option -shots 0 + } + +If no __-default__ value is specified, the option's default value will be the +empty string (but see [THE TK OPTION DATABASE](#section19)). + +The Snit man page refers to options like these as "locally defined" options. + +## How can a client set options at object creation? + +The normal convention is that the client may pass any number of options and +their values after the object's name at object creation. For example, the +__::dog__ command defined in the previous answer can now be used to create +individual dogs. Any or all of the options may be set at creation time. + + % dog spot -breed beagle -color "mottled" -akc 1 -shots 1 + ::spot + % dog fido -shots 1 + ::fido + % + +So __::spot__ is a pedigreed beagle; __::fido__ is a typical mutt, but his +owners evidently take care of him, because he's had his shots. + +*Note:* If the type defines a constructor, it can specify a different +object-creation syntax. See [CONSTRUCTORS](#section12) for more information. + +## How can a client retrieve an option's value? + +Retrieve option values using the __cget__ method: + + % spot cget -color + mottled + % fido cget -breed + mongrel + % + +## How can a client set options after object creation? + +Any number of options may be set at one time using the __configure__ instance +method. Suppose that closer inspection shows that ::fido is not a brown mongrel, +but rather a rare Arctic Boar Hound of a lovely dun color: + + % fido configure -color dun -breed "Arctic Boar Hound" + % fido cget -color + dun + % fido cget -breed + Arctic Boar Hound + +Alternatively, the __configurelist__ method takes a list of options and values; +occasionally this is more convenient: + + % set features [list -color dun -breed "Arctic Boar Hound"] + -color dun -breed {Arctic Boar Hound} + % fido configurelist $features + % fido cget -color + dun + % fido cget -breed + Arctic Boar Hound + % + +In Tcl 8.5, the __*__ keyword can be used with __configure__ in this case: + + % set features [list -color dun -breed "Arctic Boar Hound"] + -color dun -breed {Arctic Boar Hound} + % fido configure {*}$features + % fido cget -color + dun + % fido cget -breed + Arctic Boar Hound + % + +The results are the same. + +## How should an instance method access an option value? + +There are two ways an instance method can set and retrieve an option's value. +One is to use the __configure__ and __cget__ methods, as shown below. + + % snit::type dog { + option -weight 10 + + method gainWeight {} { + set wt [$self cget -weight] + incr wt + $self configure -weight $wt + } + } + ::dog + % dog fido + ::fido + % fido cget -weight + 10 + % fido gainWeight + % fido cget -weight + 11 + % + +Alternatively, Snit provides a built-in array instance variable called +__options__. The indices are the option names; the values are the option values. +The method __gainWeight__ can thus be rewritten as follows: + + method gainWeight {} { + incr options(-weight) + } + +As you can see, using the __options__ variable involves considerably less typing +and is the usual way to do it. But if you use __-configuremethod__ or +__-cgetmethod__ (described in the following answers), you might wish to use the +__configure__ and __cget__ methods anyway, just so that any special processing +you've implemented is sure to get done. Also, if the option is delegated to a +component then __configure__ and __cget__ are the only way to access it without +accessing the component directly. See [DELEGATION](#section16) for more +information. + +## How can I make an option read-only? + +Define the option with __-readonly yes__. + +Suppose you've got an option that determines how instances of your type are +constructed; it must be set at creation time, after which it's constant. For +example, a dog never changes its breed; it might or might not have had its +shots, and if not can have them at a later time. __-breed__ should be read-only, +but __-shots__ should not be. + + % snit::type dog { + option -breed -default mongrel -readonly yes + option -shots -default no + } + ::dog + % dog fido -breed retriever + ::fido + % fido configure -shots yes + % fido configure -breed terrier + option -breed can only be set at instance creation + % + +## How can I catch accesses to an option's value? + +Define a __-cgetmethod__ for the option. + +## What is a -cgetmethod? + +A __-cgetmethod__ is a method that's called whenever the related option's value +is queried via the __cget__ instance method. The handler can compute the +option's value, retrieve it from a database, or do anything else you'd like it +to do. + +Here's what the default behavior would look like if written using a +__-cgetmethod__: + + snit::type dog { + option -color -default brown -cgetmethod GetOption + + method GetOption {option} { + return $options($option) + } + } + +Any instance method can be used, provided that it takes one argument, the name +of the option whose value is to be retrieved. + +## How can I catch changes to an option's value? + +Define a __-configuremethod__ for the option. + +## What is a -configuremethod? + +A __-configuremethod__ is a method that's called whenever the related option is +given a new value via the __configure__ or __configurelist__ instance methods. +The method can pass the value on to some other object, store it in a database, +or do anything else you'd like it to do. + +Here's what the default configuration behavior would look like if written using +a __-configuremethod__: + + snit::type dog { + option -color -default brown -configuremethod SetOption + + method SetOption {option value} { + set options($option) $value + } + } + +Any instance method can be used, provided that it takes two arguments, the name +of the option and the new value. + +Note that if your method doesn't store the value in the __options__ array, the +__options__ array won't get updated. + +## How can I validate an option's value? + +Define a __-validatemethod__. + +## What is a -validatemethod? + +A __-validatemethod__ is a method that's called whenever the related option is +given a new value via the __configure__ or __configurelist__ instance methods. +It's the method's responsibility to determine whether the new value is valid, +and throw an error if it isn't. The __-validatemethod__, if any, is called +before the value is stored in the __options__ array; in particular, it's called +before the __-configuremethod__, if any. + +For example, suppose an option always takes a Boolean value. You can ensure that +the value is in fact a valid Boolean like this: + + % snit::type dog { + option -shots -default no -validatemethod BooleanOption + + method BooleanOption {option value} { + if {![string is boolean -strict $value]} { + error "expected a boolean value, got \"$value\"" + } + } + } + ::dog + % dog fido + % fido configure -shots yes + % fido configure -shots NotABooleanValue + expected a boolean value, got "NotABooleanValue" + % + +Note that the same __-validatemethod__ can be used to validate any number of +boolean options. + +Any method can be a __-validatemethod__ provided that it takes two arguments, +the option name and the new option value. + +# TYPE VARIABLES + +## What is a type variable? + +A type variable is a private variable associated with a Snit type rather than +with a particular instance of the type. In C++ and Java, the term *static member +variable* is used for the same notion. Type variables can be scalars or arrays. + +## How is a scalar type variable defined? + +Scalar type variables are defined in the type definition using the +__typevariable__ statement. You can simply name it, or you can initialize it +with a value: + + snit::type mytype { + # Define variable "greeting" and initialize it with "Howdy!" + typevariable greeting "Howdy!" + } + +Every object of type __mytype__ now has access to a single variable called +__greeting__. + +## How is an array-valued type variable defined? + +Array-valued type variables are also defined using the __typevariable__ command; +to initialize them, include the __-array__ option: + + snit::type mytype { + # Define typearray variable "greetings" + typevariable greetings -array { + formal "Good Evening" + casual "Howdy!" + } + } + +## What happens if I don't initialize a type variable? + +Variables do not really exist until they are given values. If you do not +initialize a variable when you define it, then you must be sure to assign a +value to it (in the type constructor, say) before you reference it. + +## Are there any limitations on type variable names? + +Type variable names have the same restrictions as the names of [INSTANCE +VARIABLES](#section6) do. + +## Do I need to declare my type variables in my methods? + +No. Once you've defined a type variable in the type definition, it can be used +in [INSTANCE METHODS](#section5) or [TYPE METHODS](#section9) without +declaration. This differs from normal Tcl practice, in which all non-local +variables in a proc need to be declared. + +Type variables are subject to the same speed/readability tradeoffs as instance +variables; see [Do I need to declare my instance variables in my +methods?](#subsection46) + +## How do I pass a type variable's name to another object? + +In Tk, it's common to pass a widget a variable name; for example, Tk label +widgets have a __-textvariable__ option which names the variable which will +contain the widget's text. This allows the program to update the label's value +just by assigning a new value to the variable. + +If you naively pass a type variable name to the label widget, you'll be confused +by the result; Tk will assume that the name names a global variable. Instead, +you need to provide a fully-qualified variable name. From within an instance +method or a constructor, you can fully qualify the type variable's name using +the __mytypevar__ command: + + snit::widget mywidget { + typevariable labeltext "" + + constructor {args} { + # ... + + label $win.label -textvariable [mytypevar labeltext] + + # ... + } + } + +## How do I make a type variable public? + +There are two ways to do this. The preferred way is to write a pair of [TYPE +METHODS](#section9) to set and query the type variable's value. + +Type variables are stored in the type's namespace, which has the same name as +the type itself. Thus, you can also publicize the type variable's name in your +documentation so that clients can access it directly. For example, + + snit::type mytype { + typevariable myvariable + } + + set ::mytype::myvariable "New Value" + +# TYPE METHODS + +## What is a type method? + +A type method is a procedure associated with the type itself rather than with +any specific instance of the type, and called as a subcommand of the type +command. + +## How do I define a type method? + +Type methods are defined in the type definition using the __typemethod__ +statement: + + snit::type dog { + # List of pedigreed dogs + typevariable pedigreed + + typemethod pedigreedDogs {} { + return $pedigreed + } + } + +Suppose the __dog__ type maintains a list of the names of the dogs that have +pedigrees. The __pedigreedDogs__ type method returns this list. + +The __typemethod__ statement looks just like a normal Tcl +__[proc](../../../../index.md#proc)__, except that it appears in a +__snit::type__ definition. Notice that every type method gets an implicit +argument called __type__, which contains the fully-qualified type name. + +## How does a client call a type method? + +The type method name becomes a subcommand of the type's command. For example, +assuming that the constructor adds each pedigreed dog to the list of +__pedigreedDogs__, + + snit::type dog { + option -pedigreed 0 + + # List of pedigreed dogs + typevariable pedigreed + + typemethod pedigreedDogs {} { + return $pedigreed + } + + # ... + } + + dog spot -pedigreed 1 + dog fido + + foreach dog [dog pedigreedDogs] { ... } + +## Are there any limitations on type method names? + +Not really, so long as you avoid the standard type method names: __create__, +__destroy__, and __info__. + +## How do I make a type method private? + +It's sometimes useful to define private type methods, that is, type methods +intended to be called only by other type or instance methods of the same object. + +Snit doesn't implement any access control on type methods; by convention, the +names of public methods begin with a lower-case letter, and the names of private +methods begin with an upper-case letter. + +Alternatively, a Snit __[proc](../../../../index.md#proc)__ can be used as a +private type method; see [PROCS](#section10). + +## Are there any limitations on type method arguments? + +Method argument lists are defined just like normal Tcl proc argument lists; in +particular, they can include arguments with default values and the __args__ +argument. + +However, every type method is called with an implicit argument called __type__ +that contains the name of the type command. In addition, type methods should by +convention avoid using the names of the arguments implicitly defined for +[INSTANCE METHODS](#section5). + +## How does an instance or type method call a type method? + +If an instance or type method needs to call a type method, it should use +__$type__ to do so: + + snit::type dog { + + typemethod pedigreedDogs {} { ... } + + typemethod printPedigrees {} { + foreach obj [$type pedigreedDogs] { ... } + } + } + +## How do I pass a type method as a callback? + +It's common in Tcl to pass a snippet of code to another object, for it to call +later. Because types cannot be renamed, you can just use the type name, or, if +the callback is registered from within a type method, __type__. For example, +suppose we want to print a list of pedigreed dogs when a Tk button is pushed: + + button .btn -text "Pedigrees" -command [list dog printPedigrees] + pack .btn + +Alternatively, from a method or type method you can use the __mytypemethod__ +command, just as you would use __mymethod__ to define a callback command for +[INSTANCE METHODS](#section5). + +## Can type methods be hierarchical? + +Yes, you can define hierarchical type methods in just the same way as you can +define hierarchical instance methods. See [INSTANCE METHODS](#section5) for +more. + +# PROCS + +## What is a proc? + +A Snit __[proc](../../../../index.md#proc)__ is really just a Tcl proc defined +within the type's namespace. You can use procs for private code that isn't +related to any particular instance. + +## How do I define a proc? + +Procs are defined by including a __[proc](../../../../index.md#proc)__ statement +in the type definition: + + snit::type mytype { + # Pops and returns the first item from the list stored in the + # listvar, updating the listvar + proc pop {listvar} { ... } + + # ... + } + +## Are there any limitations on proc names? + +Any name can be used, so long as it does not begin with __Snit___; names +beginning with __Snit___ are reserved for Snit's own use. However, the wise +programmer will avoid __[proc](../../../../index.md#proc)__ names +(__[set](../../../../index.md#set)__, __[list](../../../../index.md#list)__, +__if__, etc.) that would shadow standard Tcl command names. + +__[proc](../../../../index.md#proc)__ names, being private, should begin with a +capital letter according to convention; however, as there are typically no +public __[proc](../../../../index.md#proc)__s in the type's namespace it doesn't +matter much either way. + +## How does a method call a proc? + +Just like it calls any Tcl command. For example, + + snit::type mytype { + # Pops and returns the first item from the list stored in the + # listvar, updating the listvar + proc pop {listvar} { ... } + + variable requestQueue {} + + # Get one request from the queue and process it. + method processRequest {} { + set req [pop requestQueue] + } + } + +## How can I pass a proc to another object as a callback? + +The __myproc__ command returns a callback command for the +__[proc](../../../../index.md#proc)__, just as __mymethod__ does for a method. + +# TYPE CONSTRUCTORS + +## What is a type constructor? + +A type constructor is a body of code that initializes the type as a whole, +rather like a C++ static initializer. The body of a type constructor is executed +once when the type is defined, and never again. + +A type can have at most one type constructor. + +## How do I define a type constructor? + +A type constructor is defined by using the __typeconstructor__ statement in the +type definition. For example, suppose the type uses an array-valued type +variable as a look-up table, and the values in the array have to be computed at +start-up. + + % snit::type mytype { + typevariable lookupTable + + typeconstructor { + array set lookupTable {key value...} + } + } + +# CONSTRUCTORS + +## What is a constructor? + +In object-oriented programming, an object's constructor is responsible for +initializing the object completely at creation time. The constructor receives +the list of options passed to the __snit::type__ command's __create__ method and +can then do whatever it likes. That might include computing instance variable +values, reading data from files, creating other objects, updating type and +instance variables, and so forth. + +The constructor's return value is ignored (unless it's an error, of course). + +## How do I define a constructor? + +A constructor is defined by using the __constructor__ statement in the type +definition. Suppose that it's desired to keep a list of all pedigreed dogs. The +list can be maintained in a type variable and retrieved by a type method. +Whenever a dog is created, it can add itself to the list--provided that it's +registered with the American Kennel Club. + + % snit::type dog { + option -akc 0 + + typevariable akcList {} + + constructor {args} { + $self configurelist $args + + if {$options(-akc)} { + lappend akcList $self + } + } + + typemethod akclist {} { + return $akcList + } + } + ::dog + % dog spot -akc 1 + ::spot + % dog fido + ::fido + % dog akclist + ::spot + % + +## What does the default constructor do? + +If you don't provide a constructor explicitly, you get the default constructor, +which is identical to the explicitly-defined constructor shown here: + + snit::type dog { + constructor {args} { + $self configurelist $args + } + } + +When the constructor is called, __args__ will be set to the list of arguments +that follow the object's name. The constructor is allowed to interpret this list +any way it chooses; the normal convention is to assume that it's a list of +option names and values, as shown in the example above. If you simply want to +save the option values, you should use the __configurelist__ method, as shown. + +## Can I choose a different set of arguments for the constructor? + +Yes, you can. For example, suppose we wanted to be sure that the breed was +explicitly stated for every dog at creation time, and couldn't be changed +thereafter. One way to do that is as follows: + + % snit::type dog { + variable breed + + option -color brown + option -akc 0 + + constructor {theBreed args} { + set breed $theBreed + $self configurelist $args + } + + method breed {} { return $breed } + } + ::dog + % dog spot dalmatian -color spotted -akc 1 + ::spot + % spot breed + dalmatian + +The drawback is that this syntax is non-standard, and may limit the +compatibility of your new type with other people's code. For example, Snit +assumes that it can create [COMPONENTS](#section14) using the standard creation +syntax. + +## Are there any limitations on constructor arguments? + +Constructor argument lists are subject to the same limitations as those on +instance method argument lists. It has the same implicit arguments, and can +contain default values and the __args__ argument. + +## Is there anything special about writing the constructor? + +Yes. Writing the constructor can be tricky if you're delegating options to +components, and there are specific issues relating to __snit::widget__s and +__snit::widgetadaptor__s. See [DELEGATION](#section16), [WIDGETS](#section17), +[WIDGET ADAPTORS](#section18), and [THE TK OPTION DATABASE](#section19). + +# DESTRUCTORS + +## What is a destructor? + +A destructor is a special kind of method that's called when an object is +destroyed. It's responsible for doing any necessary clean-up when the object +goes away: destroying [COMPONENTS](#section14), closing files, and so forth. + +## How do I define a destructor? + +Destructors are defined by using the __destructor__ statement in the type +definition. + +Suppose we're maintaining a list of pedigreed dogs; then we'll want to remove +dogs from it when they are destroyed. + + snit::type dog { + option -akc 0 + + typevariable akcList {} + + constructor {args} { + $self configurelist $args + + if {$options(-akc)} { + lappend akcList $self + } + } + + destructor { + set ndx [lsearch $akcList $self] + + if {$ndx != -1} { + set akcList [lreplace $akcList $ndx $ndx] + } + } + + typemethod akclist {} { + return $akcList + } + } + +## Are there any limitations on destructor arguments? + +Yes; a destructor has no explicit arguments. + +## What implicit arguments are passed to the destructor? + +The destructor gets the same implicit arguments that are passed to [INSTANCE +METHODS](#section5): __type__, __selfns__, __win__, and __self__. + +## Must components be destroyed explicitly? + +Yes and no. + +Any Tk widgets created by a __snit::widget__ or __snit::widgetadaptor__ will be +destroyed automatically by Tk when the megawidget is destroyed, in keeping with +normal Tk behavior (destroying a parent widget destroys the whole tree). + +Components of normal __snit::types__, on the other hand, are never destroyed +automatically, nor are non-widget components of Snit megawidgets. If your object +creates them in its constructor, then it should generally destroy them in its +destructor. + +## Is there any special about writing a destructor? + +Yes. If an object's constructor throws an error, the object's destructor will be +called to clean up; this means that the object might not be completely +constructed when the destructor is called. This can cause the destructor to +throw its own error; the result is usually misleading, confusing, and unhelpful. +Consequently, it's important to write your destructor so that it's fail-safe. + +For example, a __dog__ might create a __tail__ component; the component will +need to be destroyed. But suppose there's an error while processing the creation +options--the destructor will be called, and there will be no __tail__ to +destroy. The simplest solution is generally to catch and ignore any errors while +destroying components. + + snit::type dog { + component tail + + constructor {args} { + $self configurelist $args + + set tail [tail %AUTO%] + } + + destructor { + catch {$tail destroy} + } + } + +# COMPONENTS + +## What is a component? + +Often an object will create and manage a number of other objects. A Snit +megawidget, for example, will often create a number of Tk widgets. These objects +are part of the main object; it is composed of them, so they are called +components of the object. + +But Snit also has a more precise meaning for [COMPONENT](#section14). The +components of a Snit object are those objects to which methods or options can be +delegated. (See [DELEGATION](#section16) for more information about delegation.) + +## How do I declare a component? + +First, you must decide what role a component plays within your object, and give +the role a name. Then, you declare the component using its role name and the +__component__ statement. The __component__ statement declares an *instance +variable* which is used to store the component's command name when the component +is created. + +For example, suppose your __dog__ object creates a __tail__ object (the better +to wag with, no doubt): + + snit::type dog { + component mytail + + constructor {args} { + # Create and save the component's command + set mytail [tail %AUTO% -partof $self] + $self configurelist $args + } + + method wag {} { + $mytail wag + } + } + +As shown here, it doesn't matter what the __tail__ object's real name is; the +__dog__ object refers to it by its component name. + +The above example shows one way to delegate the __wag__ method to the __mytail__ +component; see [DELEGATION](#section16) for an easier way. + +## How is a component named? + +A component has two names. The first name is that of the component variable; +this represents the role the component object plays within the Snit object. This +is the component name proper, and is the name used to refer to the component +within Snit code. The second name is the name of the actual component object +created by the Snit object's constructor. This second name is always a Tcl +command name, and is referred to as the component's object name. + +In the example in the previous question, the component name is __mytail__; the +__mytail__ component's object name is chosen automatically by Snit since +__%AUTO%__ was used when the component object was created. + +## Are there any limitations on component names? + +Yes. __snit::widget__ and __snit::widgetadaptor__ objects have a special +component called the __hull__ component; thus, the name __hull__ should be used +for no other purpose. + +Otherwise, since component names are in fact instance variable names they must +follow the rules for [INSTANCE VARIABLES](#section6). + +## What is an owned component? + +An *owned* component is a component whose object command's lifetime is +controlled by the __snit::type__ or __snit::widget__. + +As stated above, a component is an object to which our object can delegate +methods or options. Under this definition, our object will usually create its +component objects, but not necessarily. Consider the following: a dog object has +a tail component; but tail knows that it's part of the dog: + + snit::type dog { + component mytail + + constructor {args} { + set mytail [tail %AUTO% -partof $self] + $self configurelist $args + } + + destructor { + catch {$mytail destroy} + } + + delegate method wagtail to mytail as wag + + method bark {} { + return "$self barked." + } + } + + snit::type tail { + component mydog + option -partof -readonly yes + + constructor {args} { + $self configurelist $args + set mydog $options(-partof) + } + + method wag {} { + return "Wag, wag." + } + + method pull {} { + $mydog bark + } + } + +Thus, if you ask a dog to wag its tail, it tells its tail to wag; and if you +pull the dog's tail, the tail tells the dog to bark. In this scenario, the tail +is a component of the dog, and the dog is a component of the tail, but the dog +owns the tail and not the other way around. + +## What does the install command do? + +The __install__ command creates an owned component using a specified command, +and assigns the result to the component's instance variable. For example: + + snit::type dog { + component mytail + + constructor {args} { + # set mytail [tail %AUTO% -partof $self] + install mytail using tail %AUTO% -partof $self + $self configurelist $args + } + } + +In a __snit::type__'s code, the __install__ command shown above is equivalent to +the __set mytail__ command that's commented out. In a __snit::widget__'s or +__snit::widgetadaptor__'s, code, however, the __install__ command also queries +[THE TK OPTION DATABASE](#section19) and initializes the new component's options +accordingly. For consistency, it's a good idea to get in the habit of using +__install__ for all owned components. + +## Must owned components be created in the constructor? + +No, not necessarily. In fact, there's no reason why an object can't destroy and +recreate a component multiple times over its own lifetime. + +## Are there any limitations on component object names? + +Yes. + +Component objects which are Tk widgets or megawidgets must have valid Tk window +names. + +Component objects which are not widgets or megawidgets must have fully-qualified +command names, i.e., names which include the full namespace of the command. Note +that Snit always creates objects with fully qualified names. + +Next, the object names of components and owned by your object must be unique. +This is no problem for widget components, since widget names are always unique; +but consider the following code: + + snit::type tail { ... } + + snit::type dog { + delegate method wag to mytail + + constructor {} { + install mytail using tail mytail + } + } + +This code uses the component name, __mytail__, as the component object name. +This is not good, and here's why: Snit instance code executes in the Snit type's +namespace. In this case, the __mytail__ component is created in the __::dog::__ +namespace, and will thus have the name __::dog::mytail__. + +Now, suppose you create two dogs. Both dogs will attempt to create a tail called +__::dog::mytail__. The first will succeed, and the second will fail, since Snit +won't let you create an object if its name is already a command. Here are two +ways to avoid this situation: + +First, if the component type is a __snit::type__ you can specify __%AUTO%__ as +its name, and be guaranteed to get a unique name. This is the safest thing to +do: + + install mytail using tail %AUTO% + +If the component type isn't a __snit::type__ you can create the component in the +object's instance namespace: + + install mytail using tail ${selfns}::mytail + +Make sure you pick a unique name within the instance namespace. + +## Must I destroy the components I own? + +That depends. When a parent widget is destroyed, all child widgets are destroyed +automatically. Thus, if your object is a __snit::widget__ or +__snit::widgetadaptor__ you don't need to destroy any components that are +widgets, because they will generally be children or descendants of your +megawidget. + +If your object is an instance of __snit::type__, though, none of its owned +components will be destroyed automatically, nor will be non-widget components of +a __snit::widget__ be destroyed automatically. All such owned components must be +destroyed explicitly, or they won't be destroyed at all. + +## Can I expose a component's object command as part of my interface? + +Yes, and there are two ways to do it. The most appropriate way is usually to use +[DELEGATION](#section16). Delegation allows you to pass the options and methods +you specify along to particular components. This effectively hides the +components from the users of your type, and ensures good encapsulation. + +However, there are times when it's appropriate, not to mention simpler, just to +make the entire component part of your type's public interface. + +## How do I expose a component's object command? + +When you declare the component, specify the __component__ statement's +__-public__ option. The value of this option is the name of a method which will +be delegated to your component's object command. + +For example, supposed you've written a combobox megawidget which owns a listbox +widget, and you want to make the listbox's entire interface public. You can do +it like this: + + snit::widget combobox { + component listbox -public listbox + + constructor {args} { + install listbox using listbox $win.listbox .... + } + } + + combobox .mycombo + .mycombo listbox configure -width 30 + +Your comobox widget, __.mycombo__, now has a __listbox__ method which has all of +the same subcommands as the listbox widget itself. Thus, the above code sets the +listbox component's width to 30. + +Usually you'll let the method name be the same as the component name; however, +you can name it anything you like. + +# TYPE COMPONENTS + +## What is a type component? + +A type component is a component that belongs to the type itself instead of to a +particular instance of the type. The relationship between components and type +components is the same as the relationship between [INSTANCE +VARIABLES](#section6) and [TYPE VARIABLES](#section8). Both [INSTANCE +METHODS](#section5) and [TYPE METHODS](#section9) can be delegated to type +components. + +Once you understand [COMPONENTS](#section14) and [DELEGATION](#section16), type +components are just more of the same. + +## How do I declare a type component? + +Declare a type component using the __typecomponent__ statement. It takes the +same options (__-inherit__ and __-public__) as the __component__ statement does, +and defines a type variable to hold the type component's object command. + +Suppose in your model you've got many dogs, but only one veterinarian. You might +make the veterinarian a type component. + + snit::type veterinarian { ... } + + snit::type dog { + typecomponent vet + + # ... + } + +## How do I install a type component? + +Just use the __[set](../../../../index.md#set)__ command to assign the +component's object command to the type component. Because types (even +__snit::widget__ types) are not widgets, and do not have options anyway, the +extra features of the __install__ command are not needed. + +You'll usually install type components in the type constructor, as shown here: + + snit::type veterinarian { ... } + + snit::type dog { + typecomponent vet + + typeconstructor { + set vet [veterinarian %AUTO%] + } + } + +## Are there any limitations on type component names? + +Yes, the same as on [INSTANCE VARIABLES](#section6), [TYPE +VARIABLES](#section8), and normal [COMPONENTS](#section14). + +# DELEGATION + +## What is delegation? + +Delegation, simply put, is when you pass a task you've been given to one of your +assistants. (You do have assistants, don't you?) Snit objects can do the same +thing. The following example shows one way in which the __dog__ object can +delegate its __wag__ method and its __-taillength__ option to its __tail__ +component. + + snit::type dog { + variable mytail + + option -taillength -configuremethod SetTailOption -cgetmethod GetTailOption + + method SetTailOption {option value} { + $mytail configure $option $value + } + + method GetTailOption {option} { + $mytail cget $option + } + + method wag {} { + $mytail wag + } + + constructor {args} { + install mytail using tail %AUTO% -partof $self + $self configurelist $args + } + + } + +This is the hard way to do it, by it demonstrates what delegation is all about. +See the following answers for the easy way to do it. + +Note that the constructor calls the __configurelist__ method +__[after](../../../../index.md#after)__ it creates its __tail__; otherwise, if +__-taillength__ appeared in the list of __args__ we'd get an error. + +## How can I delegate a method to a component object? + +Delegation occurs frequently enough that Snit makes it easy. Any method can be +delegated to any component or type component by placing a single __delegate__ +statement in the type definition. (See [COMPONENTS](#section14) and [TYPE +COMPONENTS](#section15) for more information about component names.) + +For example, here's a much better way to delegate the __dog__ object's __wag__ +method: + + % snit::type dog { + delegate method wag to mytail + + constructor {} { + install mytail using tail %AUTO% + } + } + ::dog + % snit::type tail { + method wag {} { return "Wag, wag, wag."} + } + ::tail + % dog spot + ::spot + % spot wag + Wag, wag, wag. + +This code has the same effect as the code shown under the previous question: +when a __dog__'s __wag__ method is called, the call and its arguments are passed +along automatically to the __tail__ object. + +Note that when a component is mentioned in a __delegate__ statement, the +component's instance variable is defined implicitly. However, it's still good +practice to declare it explicitly using the __component__ statement. + +Note also that you can define a method name using the +__[method](../../../../index.md#method)__ statement, or you can define it using +__delegate__; you can't do both. + +## Can I delegate to a method with a different name? + +Suppose you wanted to delegate the __dog__'s __wagtail__ method to the +__tail__'s __wag__ method. After all you wag the tail, not the dog. It's easily +done: + + snit::type dog { + delegate method wagtail to mytail as wag + + constructor {args} { + install mytail using tail %AUTO% -partof $self + $self configurelist $args + } + } + +## Can I delegate to a method with additional arguments? + +Suppose the __tail__'s __wag__ method takes as an argument the number of times +the tail should be wagged. You want to delegate the __dog__'s __wagtail__ method +to the __tail__'s __wag__ method, specifying that the tail should be wagged +exactly three times. This is easily done, too: + + snit::type dog { + delegate method wagtail to mytail as {wag 3} + # ... + } + + snit::type tail { + method wag {count} { + return [string repeat "Wag " $count] + } + # ... + } + +## Can I delegate a method to something other than an object? + +Normal method delegation assumes that you're delegating a method (a subcommand +of an object command) to a method of another object (a subcommand of a different +object command). But not all Tcl objects follow Tk conventions, and not +everything you'd to which you'd like to delegate a method is necessary an +object. Consequently, Snit makes it easy to delegate a method to pretty much +anything you like using the __delegate__ statement's __using__ clause. + +Suppose your dog simulation stores dogs in a database, each dog as a single +record. The database API you're using provides a number of commands to manage +records; each takes the record ID (a string you choose) as its first argument. +For example, __saverec__ saves a record. If you let the record ID be the name of +the dog object, you can delegate the dog's __save__ method to the __saverec__ +command as follows: + + snit::type dog { + delegate method save using {saverec %s} + } + +The __%s__ is replaced with the instance name when the __save__ method is +called; any additional arguments are the appended to the resulting command. + +The __using__ clause understands a number of other %-conversions; in addition to +the instance name, you can substitute in the method name (__%m__), the type name +(__%t__), the instance namespace (__%n__), the Tk window name (__%w__), and, if +a component or typecomponent name was given in the __delegate__ statement, the +component's object command (__%c__). + +## How can I delegate a method to a type component object? + +Just exactly as you would to a component object. The __delegate method__ +statement accepts both component and type component names in its __to__ clause. + +## How can I delegate a type method to a type component object? + +Use the __delegate typemethod__ statement. It works like __delegate method__, +with these differences: first, it defines a type method instead of an instance +method; second, the __using__ clause ignores the __%s__, __%n__, and __%w__ +%-conversions. + +Naturally, you can't delegate a type method to an instance component...Snit +wouldn't know which instance should receive it. + +## How can I delegate an option to a component object? + +The first question in this section (see [DELEGATION](#section16)) shows one way +to delegate an option to a component; but this pattern occurs often enough that +Snit makes it easy. For example, every __tail__ object has a __-length__ option; +we want to allow the creator of a __dog__ object to set the tail's length. We +can do this: + + % snit::type dog { + delegate option -length to mytail + + constructor {args} { + install mytail using tail %AUTO% -partof $self + $self configurelist $args + } + } + ::dog + % snit::type tail { + option -partof + option -length 5 + } + ::tail + % dog spot -length 7 + ::spot + % spot cget -length + 7 + +This produces nearly the same result as the __-configuremethod__ and +__-cgetmethod__ shown under the first question in this section: whenever a +__dog__ object's __-length__ option is set or retrieved, the underlying __tail__ +object's option is set or retrieved in turn. + +Note that you can define an option name using the __option__ statement, or you +can define it using __delegate__; you can't do both. + +## Can I delegate to an option with a different name? + +In the previous answer we delegated the __dog__'s __-length__ option down to its +__tail__. This is, of course, wrong. The dog has a length, and the tail has a +length, and they are different. What we'd really like to do is give the __dog__ +a __-taillength__ option, but delegate it to the __tail__'s __-length__ option: + + snit::type dog { + delegate option -taillength to mytail as -length + + constructor {args} { + set mytail [tail %AUTO% -partof $self] + $self configurelist $args + } + } + +## How can I delegate any unrecognized method or option to a component object? + +It may happen that a Snit object gets most of its behavior from one of its +components. This often happens with __snit::widgetadaptors__, for example, where +we wish to slightly the modify the behavior of an existing widget. To carry on +with our __dog__ example, however, suppose that we have a __snit::type__ called +__animal__ that implements a variety of animal behaviors--moving, eating, +sleeping, and so forth. We want our __dog__ objects to inherit these same +behaviors, while adding dog-like behaviors of its own. Here's how we can give a +__dog__ methods and options of its own while delegating all other methods and +options to its __animal__ component: + + snit::type dog { + delegate option * to animal + delegate method * to animal + + option -akc 0 + + constructor {args} { + install animal using animal %AUTO% -name $self + $self configurelist $args + } + + method wag {} { + return "$self wags its tail" + } + } + +That's it. A __dog__ is now an __animal__ that has a __-akc__ option and can +__wag__ its tail. + +Note that we don't need to specify the full list of method names or option names +that __animal__ will receive. It gets anything __dog__ doesn't recognize--and if +it doesn't recognize it either, it will simply throw an error, just as it +should. + +You can also delegate all unknown type methods to a type component using +__delegate typemethod *__. + +## How can I delegate all but certain methods or options to a component? + +In the previous answer, we said that every __dog__ is an __animal__ by +delegating all unknown methods and options to the __animal__ component. But what +if the __animal__ type has some methods or options that we'd like to suppress? + +One solution is to explicitly delegate all the options and methods, and forgo +the convenience of __delegate method *__ and __delegate option *__. But if we +wish to suppress only a few options or methods, there's an easier way: + + snit::type dog { + delegate option * to animal except -numlegs + delegate method * to animal except {fly climb} + + # ... + + constructor {args} { + install animal using animal %AUTO% -name $self -numlegs 4 + $self configurelist $args + } + + # ... + } + +Dogs have four legs, so we specify that explicitly when we create the __animal__ +component, and explicitly exclude __-numlegs__ from the set of delegated +options. Similarly, dogs can neither __fly__ nor __climb__, so we exclude those +__animal__ methods as shown. + +## Can a hierarchical method be delegated? + +Yes; just specify multiple words in the delegated method's name: + + snit::type tail { + method wag {} {return "Wag, wag"} + method droop {} {return "Droop, droop"} + } + + snit::type dog { + delegate method {tail wag} to mytail + delegate method {tail droop} to mytail + + # ... + + constructor {args} { + install mytail using tail %AUTO% + $self configurelist $args + } + + # ... + } + +Unrecognized hierarchical methods can also be delegated; the following code +delegates all subcommands of the "tail" method to the "mytail" component: + + snit::type dog { + delegate method {tail *} to mytail + + # ... + } + +# WIDGETS + +## What is a snit::widget? + +A __snit::widget__ is the Snit version of what Tcl programmers usually call a +*megawidget*: a widget-like object usually consisting of one or more Tk widgets +all contained within a Tk frame. + +A __snit::widget__ is also a special kind of __snit::type__. Just about +everything in this FAQ list that relates to __snit::types__ also applies to +__snit::widgets__. + +## How do I define a snit::widget? + +__snit::widgets__ are defined using the __snit::widget__ command, just as +__snit::types__ are defined by the __snit::type__ command. + +The body of the definition can contain all of the same kinds of statements, plus +a couple of others which will be mentioned below. + +## How do snit::widgets differ from snit::types? + + - The name of an instance of a __snit::type__ can be any valid Tcl command + name, in any namespace. The name of an instance of a __snit::widget__ must + be a valid Tk widget name, and its parent widget must already exist. + + - An instance of a __snit::type__ can be destroyed by calling its __destroy__ + method. Instances of a __snit::widget__ have no destroy method; use the Tk + __destroy__ command instead. + + - Every instance of a __snit::widget__ has one predefined component called its + __hull__ component. The hull is usually a Tk + __[frame](../../../../index.md#frame)__ or __toplevel__ widget; any other + widgets created as part of the __snit::widget__ will usually be contained + within the hull. + + - __snit::widget__s can have their options receive default values from [THE TK + OPTION DATABASE](#section19). + +## What is a hull component? + +Snit can't create a Tk widget object; only Tk can do that. Thus, every instance +of a __snit::widget__ must be wrapped around a genuine Tk widget; this Tk widget +is called the *hull component*. Snit effectively piggybacks the behavior you +define (methods, options, and so forth) on top of the hull component so that the +whole thing behaves like a standard Tk widget. + +For __snit::widget__s the hull component must be a Tk widget that defines the +__-class__ option. + +__snit::widgetadaptor__s differ from __snit::widget__s chiefly in that any kind +of widget can be used as the hull component; see [WIDGET ADAPTORS](#section18). + +## How can I set the hull type for a snit::widget? + +A __snit::widget__'s hull component will usually be a Tk +__[frame](../../../../index.md#frame)__ widget; however, it may be any Tk widget +that defines the __-class__ option. You can explicitly choose the hull type you +prefer by including the __hulltype__ command in the widget definition: + + snit::widget mytoplevel { + hulltype toplevel + + # ... + } + +If no __hulltype__ command appears, the hull will be a +__[frame](../../../../index.md#frame)__. + +By default, Snit recognizes the following hull types: the Tk widgets +__[frame](../../../../index.md#frame)__, __labelframe__, __toplevel__, and the +Tile widgets __ttk::frame__, __ttk::labelframe__, and __ttk::toplevel__. To +enable the use of some other kind of widget as the hull type, you can +__lappend__ the widget command to the variable __snit::hulltypes__ (always +provided the widget defines the __-class__ option. For example, suppose Tk gets +a new widget type called a __prettyframe__: + + lappend snit::hulltypes prettyframe + + snit::widget mywidget { + hulltype prettyframe + + # ... + } + +## How should I name widgets which are components of a snit::widget? + +Every widget, whether a genuine Tk widget or a Snit megawidget, has to have a +valid Tk window name. When a __snit::widget__ is first created, its instance +name, __self__, is a Tk window name; however, if the __snit::widget__ is used as +the hull component by a __snit::widgetadaptor__ its instance name will be +changed to something else. For this reason, every __snit::widget__ method, +constructor, destructor, and so forth is passed another implicit argument, +__win__, which is the window name of the megawidget. Any children should be +named using __win__ as the root. + +Thus, suppose you're writing a toolbar widget, a frame consisting of a number of +buttons placed side-by-side. It might look something like this: + + snit::widget toolbar { + delegate option * to hull + + constructor {args} { + button $win.open -text Open -command [mymethod open] + button $win.save -text Save -command [mymethod save] + + # .... + + $self configurelist $args + + } + } + +See also the question on renaming objects, toward the top of this file. + +# WIDGET ADAPTORS + +## What is a snit::widgetadaptor? + +A __snit::widgetadaptor__ is a kind of __snit::widget__. Whereas a +__snit::widget__'s hull is automatically created and is always a Tk frame, a +__snit::widgetadaptor__ can be based on any Tk widget--or on any Snit +megawidget, or even (with luck) on megawidgets defined using some other package. + +It's called a *widget adaptor* because it allows you to take an existing widget +and customize its behavior. + +## How do I define a snit::widgetadaptor? + +Use the __snit::widgetadaptor__ command. The definition for a +__snit::widgetadaptor__ looks just like that for a __snit::type__ or +__snit::widget__, except that the constructor must create and install the hull +component. + +For example, the following code creates a read-only text widget by the simple +device of turning its __insert__ and __delete__ methods into no-ops. Then, we +define new methods, __ins__ and __del__, which get delegated to the hull +component as __insert__ and __delete__. Thus, we've adapted the text widget and +given it new behavior while still leaving it fundamentally a text widget. + + ::snit::widgetadaptor rotext { + + constructor {args} { + # Create the text widget; turn off its insert cursor + installhull using text -insertwidth 0 + + # Apply any options passed at creation time. + $self configurelist $args + } + + # Disable the text widget's insert and delete methods, to + # make this readonly. + method insert {args} {} + method delete {args} {} + + # Enable ins and del as synonyms, so the program can insert and + # delete. + delegate method ins to hull as insert + delegate method del to hull as delete + + # Pass all other methods and options to the real text widget, so + # that the remaining behavior is as expected. + delegate method * to hull + delegate option * to hull + } + +The most important part is in the constructor. Whereas __snit::widget__ creates +the hull for you, __snit::widgetadaptor__ cannot -- it doesn't know what kind of +widget you want. So the first thing the constructor does is create the hull +component (a Tk text widget in this case), and then installs it using the +__installhull__ command. + +*Note:* There is no instance command until you create one by installing a hull +component. Any attempt to pass methods to __$self__ prior to calling +__installhull__ will fail. + +## Can I adapt a widget created elsewhere in the program? + +Yes. + +At times, it can be convenient to adapt a pre-existing widget instead of +creating your own. For example, the Bwidget __PagesManager__ widget manages a +set of __[frame](../../../../index.md#frame)__ widgets, only one of which is +visible at a time. The application chooses which +__[frame](../../../../index.md#frame)__ is visible. All of the These +__[frame](../../../../index.md#frame)__s are created by the __PagesManager__ +itself, using its __add__ method. It's convenient to adapt these frames to do +what we'd like them to do. + +In a case like this, the Tk widget will already exist when the +__snit::widgetadaptor__ is created. Snit provides an alternate form of the +__installhull__ command for this purpose: + + snit::widgetadaptor pageadaptor { + constructor {args} { + # The widget already exists; just install it. + installhull $win + + # ... + } + } + +## Can I adapt another megawidget? + +Maybe. If the other megawidget is a __snit::widget__ or __snit::widgetadaptor__, +then yes. If it isn't then, again, maybe. You'll have to try it and see. You're +most likely to have trouble with widget destruction--you have to make sure that +your megawidget code receives the ____ event before the megawidget +you're adapting does. + +# THE TK OPTION DATABASE + +## What is the Tk option database? + +The Tk option database is a database of default option values maintained by Tk +itself; every Tk application has one. The concept of the option database derives +from something called the X Windows resource database; however, the option +database is available in every Tk implementation, including those which do not +use the X Windows system (e.g., Microsoft Windows). + +Full details about the Tk option database are beyond the scope of this document; +both *Practical Programming in Tcl and Tk* by Welch, Jones, and Hobbs, and +*Effective Tcl/Tk Programming* by Harrison and McClennan., have good +introductions to it. + +Snit is implemented so that most of the time it will simply do the right thing +with respect to the option database, provided that the widget developer does the +right thing by Snit. The body of this section goes into great deal about what +Snit requires. The following is a brief statement of the requirements, for +reference. + + - If the widget's default widget class is not what is desired, set it + explicitly using the __widgetclass__ statement in the widget definition. + + - When defining or delegating options, specify the resource and class names + explicitly when necessary. + + - Use the __installhull using__ command to create and install the hull for + __snit::widgetadaptor__s. + + - Use the __install__ command to create and install all components which are + widgets. + + - Use the __install__ command to create and install components which aren't + widgets if you'd like them to receive option values from the option + database. + +The interaction of Tk widgets with the option database is a complex thing; the +interaction of Snit with the option database is even more so, and repays +attention to detail. + +## Do snit::types use the Tk option database? + +No, they don't; querying the option database requires a Tk window name, and +__snit::type__s don't have one. + +If you create an instance of a __snit::type__ as a component of a +__snit::widget__ or __snit::widgetadaptor__, on the other hand, and if any +options are delegated to the component, and if you use __install__ to create and +install it, then the megawidget will query the option database on the +__snit::type__'s behalf. This might or might not be what you want, so take care. + +## What is my snit::widget's widget class? + +Every Tk widget has a "widget class": a name that is used when adding option +settings to the database. For Tk widgets, the widget class is the same as the +widget command name with an initial capital. For example, the widget class of +the Tk __button__ widget is __Button__. + +Similarly, the widget class of a __snit::widget__ defaults to the unqualified +type name with the first letter capitalized. For example, the widget class of + + snit::widget ::mylibrary::scrolledText { ... } + +is __ScrolledText__. + +The widget class can also be set explicitly using the __widgetclass__ statement +within the __snit::widget__ definition: + + snit::widget ::mylibrary::scrolledText { + widgetclass Text + + # ... + } + +The above definition says that a __scrolledText__ megawidget has the same widget +class as an ordinary __[text](../../../../index.md#text)__ widget. This might or +might not be a good idea, depending on how the rest of the megawidget is +defined, and how its options are delegated. + +## What is my snit::widgetadaptor's widget class? + +The widget class of a __snit::widgetadaptor__ is just the widget class of its +hull widget; Snit has no control over this. + +Note that the widget class can be changed only for +__[frame](../../../../index.md#frame)__ and __toplevel__ widgets, which is why +these are the valid hull types for __snit::widget__s. + +Try to use __snit::widgetadaptor__s only to make small modifications to another +widget's behavior. Then, it will usually not make sense to change the widget's +widget class anyway. + +## What are option resource and class names? + +Every Tk widget option has three names: the option name, the resource name, and +the class name. The option name begins with a hyphen and is all lowercase; it's +used when creating widgets, and with the __configure__ and __cget__ commands. + +The resource and class names are used to initialize option default values by +querying the option database. The resource name is usually just the option name +minus the hyphen, but may contain uppercase letters at word boundaries; the +class name is usually just the resource name with an initial capital, but not +always. For example, here are the option, resource, and class names for several +Tk __[text](../../../../index.md#text)__ widget options: + + -background background Background + -borderwidth borderWidth BorderWidth + -insertborderwidth insertBorderWidth BorderWidth + -padx padX Pad + +As is easily seen, sometimes the resource and class names can be inferred from +the option name, but not always. + +## What are the resource and class names for my megawidget's options? + +For options implicitly delegated to a component using __delegate option *__, the +resource and class names will be exactly those defined by the component. The +__configure__ method returns these names, along with the option's default and +current values: + + % snit::widget mytext { + delegate option * to text + + constructor {args} { + install text using text .text + # ... + } + + # ... + } + ::mytext + % mytext .text + .text + % .text configure -padx + -padx padX Pad 1 1 + % + +For all other options (whether locally defined or explicitly delegated), the +resource and class names can be defined explicitly, or they can be allowed to +have default values. + +By default, the resource name is just the option name minus the hyphen; the the +class name is just the option name with an initial capital letter. For example, +suppose we explicitly delegate "-padx": + + % snit::widget mytext { + option -myvalue 5 + + delegate option -padx to text + delegate option * to text + + constructor {args} { + install text using text .text + # ... + } + + # ... + } + ::mytext + % mytext .text + .text + % .text configure -myvalue + -myvalue myvalue Myvalue 5 5 + % .text configure -padx + -padx padx Padx 1 1 + % + +Here the resource and class names are chosen using the default rules. Often +these rules are sufficient, but in the case of "-padx" we'd most likely prefer +that the option's resource and class names are the same as for the built-in Tk +widgets. This is easily done: + + % snit::widget mytext { + delegate option {-padx padX Pad} to text + + # ... + } + ::mytext + % mytext .text + .text + % .text configure -padx + -padx padX Pad 1 1 + % + +## How does Snit initialize my megawidget's locally-defined options? + +The option database is queried for each of the megawidget's locally-defined +options, using the option's resource and class name. If the result isn't "", +then it replaces the default value given in widget definition. In either case, +the default can be overridden by the caller. For example, + + option add *Mywidget.texture pebbled + + snit::widget mywidget { + option -texture smooth + # ... + } + + mywidget .mywidget -texture greasy + +Here, __-texture__ would normally default to "smooth", but because of the entry +added to the option database it defaults to "pebbled". However, the caller has +explicitly overridden the default, and so the new widget will be "greasy". + +## How does Snit initialize delegated options? + +That depends on whether the options are delegated to the hull, or to some other +component. + +## How does Snit initialize options delegated to the hull? + +A __snit::widget__'s hull is a widget, and given that its class has been set it +is expected to query the option database for itself. The only exception concerns +options that are delegated to it with a different name. Consider the following +code: + + option add *Mywidget.borderWidth 5 + option add *Mywidget.relief sunken + option add *Mywidget.hullbackground red + option add *Mywidget.background green + + snit::widget mywidget { + delegate option -borderwidth to hull + delegate option -hullbackground to hull as -background + delegate option * to hull + # ... + } + + mywidget .mywidget + + set A [.mywidget cget -relief] + set B [.mywidget cget -hullbackground] + set C [.mywidget cget -background] + set D [.mywidget cget -borderwidth] + +The question is, what are the values of variables A, B, C and D? + +The value of A is "sunken". The hull is a Tk frame which has been given the +widget class __Mywidget__; it will automatically query the option database and +pick up this value. Since the __-relief__ option is implicitly delegated to the +hull, Snit takes no action. + +The value of B is "red". The hull will automatically pick up the value "green" +for its __-background__ option, just as it picked up the __-relief__ value. +However, Snit knows that __-hullbackground__ is mapped to the hull's +__-background__ option; hence, it queries the option database for +__-hullbackground__ and gets "red" and updates the hull accordingly. + +The value of C is also "red", because __-background__ is implicitly delegated to +the hull; thus, retrieving it is the same as retrieving __-hullbackground__. +Note that this case is unusual; the __-background__ option should probably have +been excluded using the delegate statement's __except__ clause, or (more likely) +delegated to some other component. + +The value of D is "5", but not for the reason you think. Note that as it is +defined above, the resource name for __-borderwidth__ defaults to +__borderwidth__, whereas the option database entry is __borderWidth__, in +accordance with the standard Tk naming for this option. As with __-relief__, the +hull picks up its own __-borderwidth__ option before Snit does anything. Because +the option is delegated under its own name, Snit assumes that the correct thing +has happened, and doesn't worry about it any further. To avoid confusion, the +__-borderwidth__ option should have been delegated like this: + + delegate option {-borderwidth borderWidth BorderWidth} to hull + +For __snit::widgetadaptor__s, the case is somewhat altered. Widget adaptors +retain the widget class of their hull, and the hull is not created automatically +by Snit. Instead, the __snit::widgetadaptor__ must call __installhull__ in its +constructor. The normal way to do this is as follows: + + snit::widgetadaptor mywidget { + # ... + constructor {args} { + # ... + installhull using text -foreground white + # ... + } + # ... + } + +In this case, the __installhull__ command will create the hull using a command +like this: + + set hull [text $win -foreground white] + +The hull is a __[text](../../../../index.md#text)__ widget, so its widget class +is __Text__. Just as with __snit::widget__ hulls, Snit assumes that it will pick +up all of its normal option values automatically, without help from Snit. +Options delegated from a different name are initialized from the option database +in the same way as described above. + +In earlier versions of Snit, __snit::widgetadaptor__s were expected to call +__installhull__ like this: + + installhull [text $win -foreground white] + +This form still works--but Snit will not query the option database as described +above. + +## How does Snit initialize options delegated to other components? + +For hull components, Snit assumes that Tk will do most of the work +automatically. Non-hull components are somewhat more complicated, because they +are matched against the option database twice. + +A component widget remains a widget still, and is therefore initialized from the +option database in the usual way. A __[text](../../../../index.md#text)__ widget +remains a __[text](../../../../index.md#text)__ widget whether it is a component +of a megawidget or not, and will be created as such. + +But then, the option database is queried for all options delegated to the +component, and the component is initialized accordingly--provided that the +__install__ command is used to create it. + +Before option database support was added to Snit, the usual way to create a +component was to simply create it in the constructor and assign its command name +to the component variable: + + snit::widget mywidget { + delegate option -background to myComp + + constructor {args} { + set myComp [text $win.text -foreground black] + } + } + +The drawback of this method is that Snit has no opportunity to initialize the +component properly. Hence, the following approach is now used: + + snit::widget mywidget { + delegate option -background to myComp + + constructor {args} { + install myComp using text $win.text -foreground black + } + } + +The __install__ command does the following: + + - Builds a list of the options explicitly included in the __install__ + command--in this case, __-foreground__. + + - Queries the option database for all options delegated explicitly to the + named component. + + - Creates the component using the specified command, after inserting into it a + list of options and values read from the option database. Thus, the + explicitly included options (like __-foreground__) will override anything + read from the option database. + + - If the widget definition implicitly delegated options to the component using + __delegate option *__, then Snit calls the newly created component's + __configure__ method to receive a list of all of the component's options. + From this Snit builds a list of options implicitly delegated to the + component which were not explicitly included in the __install__ command. For + all such options, Snit queries the option database and configures the + component accordingly. + +You don't really need to know all of this; just use __install__ to install your +components, and Snit will try to do the right thing. + +## What happens if I install a non-widget as a component of widget? + +A __snit::type__ never queries the option database. However, a __snit::widget__ +can have non-widget components. And if options are delegated to those +components, and if the __install__ command is used to install those components, +then they will be initialized from the option database just as widget components +are. + +However, when used within a megawidget, __install__ assumes that the created +component uses a reasonably standard widget-like creation syntax. If it doesn't, +don't use __install__. + +# ENSEMBLE COMMANDS + +## What is an ensemble command? + +An ensemble command is a command with subcommands. Snit objects are all ensemble +commands; however, the term more usually refers to commands like the standard +Tcl commands __[string](../../../../index.md#string)__, +__[file](../../../../index.md#file)__, and __clock__. In a sense, these are +singleton objects--there's only one instance of them. + +## How can I create an ensemble command using Snit? + +There are two ways--as a __snit::type__, or as an instance of a __snit::type__. + +## How can I create an ensemble command using an instance of a snit::type? + +Define a type whose [INSTANCE METHODS](#section5) are the subcommands of your +ensemble command. Then, create an instance of the type with the desired name. + +For example, the following code uses [DELEGATION](#section16) to create a +work-alike for the standard __[string](../../../../index.md#string)__ command: + + snit::type ::mynamespace::mystringtype { + delegate method * to stringhandler + + constructor {} { + set stringhandler string + } + } + + ::mynamespace::mystringtype mystring + +We create the type in a namespace, so that the type command is hidden; then we +create a single instance with the desired name-- __mystring__, in this case. + +This method has two drawbacks. First, it leaves the type command floating about. +More seriously, your shiny new ensemble command will have __info__ and +__destroy__ subcommands that you probably have no use for. But read on. + +## How can I create an ensemble command using a snit::type? + +Define a type whose [TYPE METHODS](#section9) are the subcommands of your +ensemble command. + +For example, the following code uses [DELEGATION](#section16) to create a +work-alike for the standard __[string](../../../../index.md#string)__ command: + + snit::type mystring { + delegate typemethod * to stringhandler + + typeconstructor { + set stringhandler string + } + } + +Now the type command itself is your ensemble command. + +This method has only one drawback, and though it's major, it's also +surmountable. Your new ensemble command will have __create__, __info__ and +__destroy__ subcommands you don't want. And worse yet, since the __create__ +method can be implicit, users of your command will accidentally be creating +instances of your __mystring__ type if they should mispell one of the +subcommands. The command will succeed--the first time--but won't do what's +wanted. This is very bad. + +The work around is to set some [PRAGMAS](#section21), as shown here: + + snit::type mystring { + pragma -hastypeinfo no + pragma -hastypedestroy no + pragma -hasinstances no + + delegate typemethod * to stringhandler + + typeconstructor { + set stringhandler string + } + } + +Here we've used the __pragma__ statement to tell Snit that we don't want the +__info__ typemethod or the __destroy__ typemethod, and that our type has no +instances; this eliminates the __create__ typemethod and all related code. As a +result, our ensemble command will be well-behaved, with no unexpected +subcommands. + +# PRAGMAS + +## What is a pragma? + +A pragma is an option you can set in your type definitions that affects how the +type is defined and how it works once it is defined. + +## How do I set a pragma? + +Use the __pragma__ statement. Each pragma is an option with a value; each time +you use the __pragma__ statement you can set one or more of them. + +## How can I get rid of the "info" type method? + +Set the __-hastypeinfo__ pragma to __no__: + + snit::type dog { + pragma -hastypeinfo no + # ... + } + +Snit will refrain from defining the __info__ type method. + +## How can I get rid of the "destroy" type method? + +Set the __-hastypedestroy__ pragma to __no__: + + snit::type dog { + pragma -hastypedestroy no + # ... + } + +Snit will refrain from defining the __destroy__ type method. + +## How can I get rid of the "create" type method? + +Set the __-hasinstances__ pragma to __no__: + + snit::type dog { + pragma -hasinstances no + # ... + } + +Snit will refrain from defining the __create__ type method; if you call the type +command with an unknown method name, you'll get an error instead of a new +instance of the type. + +This is useful if you wish to use a __snit::type__ to define an ensemble command +rather than a type with instances. + +Pragmas __-hastypemethods__ and __-hasinstances__ cannot both be false (or +there'd be nothing left). + +## How can I get rid of type methods altogether? + +Normal Tk widget type commands don't have subcommands; all they do is create +widgets--in Snit terms, the type command calls the __create__ type method +directly. To get the same behavior from Snit, set the __-hastypemethods__ pragma +to __no__: + + snit::type dog { + pragma -hastypemethods no + #... + } + + # Creates ::spot + dog spot + + # Tries to create an instance called ::create + dog create spot + +Pragmas __-hastypemethods__ and __-hasinstances__ cannot both be false (or +there'd be nothing left). + +## Why can't I create an object that replaces an old object with the same name? + +Up until Snit 0.95, you could use any name for an instance of a __snit::type__, +even if the name was already in use by some other object or command. You could +do the following, for example: + + snit::type dog { ... } + + dog proc + +You now have a new dog named "proc", which is probably not something that you +really wanted to do. As a result, Snit now throws an error if your chosen +instance name names an existing command. To restore the old behavior, set the +__-canreplace__ pragma to __yes__: + + snit::type dog { + pragma -canreplace yes + # ... + } + +## How can I make my simple type run faster? + +In Snit 1.x, you can set the __-simpledispatch__ pragma to __yes__. + +Snit 1.x method dispatch is both flexible and fast, but the flexibility comes +with a price. If your type doesn't require the flexibility, the +__-simpledispatch__ pragma allows you to substitute a simpler dispatch mechanism +that runs quite a bit faster. The limitations are these: + + - Methods cannot be delegated. + + - __uplevel__ and __upvar__ do not work as expected: the caller's scope is two + levels up rather than one. + + - The option-handling methods (__cget__, __configure__, and __configurelist__) + are very slightly slower. + +In Snit 2.2, the __-simpledispatch__ macro is obsolete, and ignored; all Snit +2.2 method dispatch is faster than Snit 1.x's __-simpledispatch__. + +# MACROS + +## What is a macro? + +A Snit macro is nothing more than a Tcl proc that's defined in the Tcl +interpreter used to compile Snit type definitions. + +## What are macros good for? + +You can use Snit macros to define new type definition syntax, and to support +conditional compilation. + +## How do I do conditional compilation? + +Suppose you want your type to use a fast C extension if it's available; +otherwise, you'll fallback to a slower Tcl implementation. You want to define +one set of methods in the first case, and another set in the second case. But +how can your type definition know whether the fast C extension is available or +not? + +It's easily done. Outside of any type definition, define a macro that returns 1 +if the extension is available, and 0 otherwise: + + if {$gotFastExtension} { + snit::macro fastcode {} {return 1} + } else { + snit::macro fastcode {} {return 0} + } + +Then, use your macro in your type definition: + + snit::type dog { + + if {[fastcode]} { + # Fast methods + method bark {} {...} + method wagtail {} {...} + } else { + # Slow methods + method bark {} {...} + method wagtail {} {...} + } + } + +## How do I define new type definition syntax? + +Use a macro. For example, your __snit::widget__'s __-background__ option should +be propagated to a number of component widgets. You could implement that like +this: + + snit::widget mywidget { + option -background -default white -configuremethod PropagateBackground + + method PropagateBackground {option value} { + $comp1 configure $option $value + $comp2 configure $option $value + $comp3 configure $option $value + } + } + +For one option, this is fine; if you've got a number of options, it becomes +tedious and error prone. So package it as a macro: + + snit::macro propagate {option "to" components} { + option $option -configuremethod Propagate$option + + set body "\n" + + foreach comp $components { + append body "\$$comp configure $option \$value\n" + } + + method Propagate$option {option value} $body + } + +Then you can use it like this: + + snit::widget mywidget { + option -background default -white + option -foreground default -black + + propagate -background to {comp1 comp2 comp3} + propagate -foreground to {comp1 comp2 comp3} + } + +## Are there are restrictions on macro names? + +Yes, there are. You can't redefine any standard Tcl commands or Snit type +definition statements. You can use any other command name, including the name of +a previously defined macro. + +If you're using Snit macros in your application, go ahead and name them in the +global namespace, as shown above. But if you're using them to define types or +widgets for use by others, you should define your macros in the same namespace +as your types or widgets. That way, they won't conflict with other people's +macros. + +If my fancy __snit::widget__ is called __::mylib::mywidget__, for example, then +I should define my __propagate__ macro as __::mylib::propagate__: + + snit::macro mylib::propagate {option "to" components} { ... } + + snit::widget ::mylib::mywidget { + option -background default -white + option -foreground default -black + + mylib::propagate -background to {comp1 comp2 comp3} + mylib::propagate -foreground to {comp1 comp2 comp3} + } + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *snit* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[BWidget](../../../../index.md#bwidget), [C++](../../../../index.md#c_), [Incr +Tcl](../../../../index.md#incr_tcl), [adaptors](../../../../index.md#adaptors), +[class](../../../../index.md#class), [mega +widget](../../../../index.md#mega_widget), +[object](../../../../index.md#object), [object +oriented](../../../../index.md#object_oriented), +[widget](../../../../index.md#widget), [widget +adaptors](../../../../index.md#widget_adaptors) + +# CATEGORY + +Programming tools + +# COPYRIGHT + +Copyright © 2003-2006, by William H. Duquette ADDED embedded/md/tcllib/files/modules/soundex/soundex.md Index: embedded/md/tcllib/files/modules/soundex/soundex.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/soundex/soundex.md @@ -0,0 +1,82 @@ + +[//000000001]: # (soundex - Soundex) +[//000000002]: # (Generated from file 'soundex.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (soundex(n) 1.0 tcllib "Soundex") + +# NAME + +soundex - Soundex + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [EXAMPLES](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require soundex ?1.0? + +[__::soundex::knuth__ *string*](#1) + +# DESCRIPTION + +This package provides soundex algorithms which allow the comparison of words +based on their phonetic likeness. + +Currently only an algorithm by Knuth is provided, which is tuned to english +names and words. + + - __::soundex::knuth__ *string* + + Computes the soundex code of the input *string* using Knuth's algorithm and + returns it as the result of the command. + +# EXAMPLES + + % ::soundex::knuth Knuth + K530 + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *soundex* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[knuth](../../../../index.md#knuth), [soundex](../../../../index.md#soundex), +[text comparison](../../../../index.md#text_comparison), [text +likeness](../../../../index.md#text_likeness) + +# CATEGORY + +Hashes, checksums, and encryption + +# COPYRIGHT + +Copyright © ????, Algorithm: Donald E. Knuth +Copyright © 2003, Documentation: Andreas Kupries +Copyright © 1998, Tcl port: Evan Rempel ADDED embedded/md/tcllib/files/modules/stooop/stooop.md Index: embedded/md/tcllib/files/modules/stooop/stooop.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/stooop/stooop.md @@ -0,0 +1,247 @@ + +[//000000001]: # (stooop - Simple Tcl Only Object Oriented Programming) +[//000000002]: # (Generated from file 'stooop.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (stooop(n) 4.4.1 tcllib "Simple Tcl Only Object Oriented Programming") + +# NAME + +stooop - Object oriented extension. + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [DEBUGGING](#section2) + + - [EXAMPLES](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.3 +package require stooop ?4.4.1? + +[__::stooop::class__ *name body*](#1) +[__::stooop::new__ *class* ?*arg arg ...*?](#2) +[__::stooop::delete__ *object* ?*object ...*?](#3) +[__::stooop::virtual__ __proc__ *name* {__this__ ?*arg arg ...*?} ?*body*?](#4) +[__::stooop::classof__ *object*](#5) +[__::stooop::new__ *object*](#6) +[__::stooop::printObjects__ ?*pattern*?](#7) +[__::stooop::record__](#8) +[__::stooop::report__ ?*pattern*?](#9) + +# DESCRIPTION + +This package provides commands to extend Tcl in an object oriented manner, using +a familiar C++ like syntax and behaviour. Stooop only introduces a few new +commands: __[class](../../../../index.md#class)__, __new__, __delete__, +__virtual__ and __classof__. Along with a few coding conventions, that is +basically all you need to know to use stooop. Stooop is meant to be as simple to +use as possible. + +This manual is very succinct and is to be used as a quick reminder for the +programmer, who should have read the thorough [stooop_man.html](stooop_man.html) +HTML documentation at this point. + + - __::stooop::class__ *name body* + + This command creates a class. The body, similar in contents to a Tcl + namespace (which a class actually also is), contains member procedure + definitions. Member procedures can also be defined outside the class body, + by prefixing their name with __class::__, as you would proceed with + namespace procedures. + + * __[proc](../../../../index.md#proc)__ *class* {__this__ ?*arg arg ...*?} ?*base* {?*arg arg ...*?} ...? *body* + + This is the constructor procedure for the class. It is invoked following + a __new__ invocation on the class. It must have the same name as the + class and a first argument named __this__. Any number of base classes + specifications, including arguments to be passed to their constructor, + are allowed before the actual body of the procedure. + + * __[proc](../../../../index.md#proc)__ ~*class* {__this__} *body* + + This is the destructor procedure for the class. It is invoked following + a __delete__ invocation. Its name must be the concatenation of a single + __~__ character followed by the class name (as in C++). It must have a + single argument named __this__. + + * __[proc](../../../../index.md#proc)__ *name* {__this__ ?*arg arg ...*?} *body* + + This is a member procedure of the class, as its first argument is named + __this__. It allows a simple access of member data for the object + referenced by __this__ inside the procedure. For example: + + set ($this,data) 0 + + * __[proc](../../../../index.md#proc)__ *name* {?*arg arg ...*?} *body* + + This is a static (as in C++) member procedure of the class, as its first + argument is not named __this__. Static (global) class data can be + accessed as in: + + set (data) 0 + + * __[proc](../../../../index.md#proc)__ *class* {__this copy__} *body* + + This is the optional copy procedure for the class. It must have the same + name as the class and exactly 2 arguments named __this__ and __copy__. + It is invoked following a __new__ invocation on an existing object of + the class. + + - __::stooop::new__ *class* ?*arg arg ...*? + + This command is used to create an object. The first argument is the class + name and is followed by the arguments needed by the corresponding class + constructor. A unique identifier for the object just created is returned. + + - __::stooop::delete__ *object* ?*object ...*? + + This command is used to delete one or several objects. It takes one or more + object identifiers as argument(s). + + - __::stooop::virtual__ __proc__ *name* {__this__ ?*arg arg ...*?} ?*body*? + + The __virtual__ specifier may be used on member procedures to achieve + dynamic binding. A procedure in a base class can then be redefined + (overloaded) in the derived class(es). If the base class procedure is + invoked on an object, it is actually the derived class procedure which is + invoked, if it exists. If the base class procedure has no body, then it is + considered to be a pure virtual and the derived class procedure is always + invoked. + + - __::stooop::classof__ *object* + + This command returns the class of the existing object passed as single + parameter. + + - __::stooop::new__ *object* + + This command is used to create an object by copying an existing object. The + copy constructor of the corresponding class is invoked if it exists, + otherwise a simple copy of the copied object data members is performed. + +# DEBUGGING + + - Environment variables + + * __STOOOPCHECKDATA__ + + Setting this variable to any true value will cause stooop to check for + invalid member or class data access. + + * __STOOOPCHECKPROCEDURES__ + + Setting this variable to any true value will cause stooop to check for + invalid member procedure arguments and pure interface classes + instanciation. + + * __STOOOPCHECKALL__ + + Setting this variable to any true value will cause stooop to activate + both procedure and data member checking. + + * __STOOOPCHECKOBJECTS__ + + Setting this variable to any true value will cause stooop to activate + object checking. The following stooop namespace procedures then become + available for debugging: __printObjects__, + __[record](../../../../index.md#record)__ and + __[report](../report/report.md)__. + + * __STOOOPTRACEPROCEDURES__ + + Setting this environment variable to either __stdout__, __stderr__ or a + file name, activates procedure tracing. The stooop library will then + output to the specified channel 1 line of informational text for each + member procedure invocation. + + * __STOOOPTRACEPROCEDURESFORMAT__ + + Defines the trace procedures output format. Defaults to __"class: %C, + procedure: %p, object: %O, arguments: %a"__. + + * __STOOOPTRACEDATA__ + + Setting this environment variable to either __stdout__, __stderr__ or a + file name, activates data tracing. The stooop library will then output + to the specified channel 1 line of informational text for each member + data access. + + * __STOOOPTRACEDATAFORMAT__ + + Defines the trace data output format. Defaults to __"class: %C, + procedure: %p, array: %A, object: %O, member: %m, operation: %o, value: + %v"__. + + * __STOOOPTRACEDATAOPERATIONS__ + + When tracing data output, by default, all read, write and unsetting + accesses are reported, but the user can set this variable to any + combination of the letters __r__, __w__, and __u__ for more specific + tracing (please refer to the __[trace](../../../../index.md#trace)__ Tcl + manual page for more information). + + * __STOOOPTRACEALL__ + + Setting this environment variable to either __stdout__, __stderr__ or a + file name, enables both procedure and data tracing. + + - __::stooop::printObjects__ ?*pattern*? + + Prints an ordered list of existing objects, in creation order, oldest first. + Each output line contains the class name, object identifier and the + procedure within which the creation occurred. The optional pattern argument + (as in the Tcl __string match__ command) can be used to limit the output to + matching class names. + + - __::stooop::record__ + + When invoked, a snapshot of all existing stooop objects is taken. Reporting + can then be used at a later time to see which objects were created or + deleted in the interval. + + - __::stooop::report__ ?*pattern*? + + Prints the created and deleted objects since the __::stooop::record__ + procedure was invoked last. If present, the pattern argument limits the + output to matching class names. + +# EXAMPLES + +Please see the full HTML documentation in [stooop_man.html](stooop_man.html). + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *stooop* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[C++](../../../../index.md#c_), [class](../../../../index.md#class), +[object](../../../../index.md#object), [object +oriented](../../../../index.md#object_oriented) + +# CATEGORY + +Programming tools ADDED embedded/md/tcllib/files/modules/stooop/switched.md Index: embedded/md/tcllib/files/modules/stooop/switched.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/stooop/switched.md @@ -0,0 +1,280 @@ + +[//000000001]: # (switched - Simple Tcl Only Object Oriented Programming) +[//000000002]: # (Generated from file 'switched.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (switched(n) 2.2.1 tcllib "Simple Tcl Only Object Oriented Programming") + +# NAME + +switched - switch/option management. + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.3 +package require switched ?2.2.1? + +[____ __complete__ *this*](#1) +[____ __options__ *this*](#2) +[____ __set-__option____ *this* *value*](#3) + +# DESCRIPTION + +The __switched__ class serves as base class for user classes with switch / +option configuration procedures. It provides facilities for managing options +through a simple interface. + +For example: + + set vehicle [new car -length 4.5 -width 2 -power 100 -fuel diesel] + puts "my car was running on [switched::cget $vehicle -fuel]" + switched::configure $vehicle -power 40 -fuel electricity + puts "but is now running on clean [switched::cget $vehicle -fuel]" + +Of course, as you might have guessed, the __car__ class is derived from the +__switched__ class. Let us see how it works: + + class car { + proc car {this args} switched {$args} { + # car specific initialization code here + switched::complete $this + } + ... + } + +The switched class constructor takes the optional configuration option / value +pairs as parameters. The switched class layer then completely manages the +switched options: it checks their validity, stores their values and provides a +clean interface to the user layer configuration setting procedures. + +The switched class members available to the programmer are: + + - ____ __complete__ *this* + + This procedure is used to tell the switched layer that the derived class + object (a car in the examples) is completely built. At that time, the + initial configuration of the switched object occurs, using default option + values (see procedure __options__) eventually overridden by construction + time values, passed at the time of the __new__ operator invocation. This + procedure must be called only once, usually around or at the end of the + derived class constructor. (*Note*: Also check the __complete__ data member + later in this chapter). + + - ____ __options__ *this* + + This procedure must return the configuration description for *all* options + that the switched object will accept. It is a pure virtual member procedure + and therefore its implementation is *mandatory* in the derived class layer. + The procedure must return a list of lists. Each list pertains to a single + option and is composed of the switch name, the default value for the option + and an optional initial value. For example: + + class car { + ... + proc options {this} { + return [list [list -fuel petrol petrol] [list -length {} {}] [list -power {} {}] [list -width {} {}] ] + } + proc set-fuel {this value} { + ... + } + ... + } + + In this case, 4 options are specified: __fuel__, __length__, __power__ and + __width__. The default and initial values for the __fuel__ option are + identical and set to __petrol__. For the other options, values are all + empty. + + For each option, there must be a corresponding __set-__option____ procedure + defined in the derived class layer. For example, since we defined a __fuel__ + option, there is a __set-fuel__ procedure in the car class. The parameters + always are the object identifier (since this is not a static procedure, but + rather a dynamically defined virtual one), followed by the new value for the + option. A __set-__option____ procedure is only invoked if the new value + differs from the current one (a caching scheme for improving performance), + or if there is no initial value set in the __options__ procedure for that + option. + + In this procedure, if the initial value differs from the default value or is + omitted, then initial configuration is forced and the corresponding + __set-__option____ procedure is invoked by the switched __complete__ + procedure located at the end of the derived class constructor. For example: + + class car { + ... + proc options {this} { + return [list [list -fuel petrol] [list -length {} {}] [list -power 100 50] [list -width {} {}] ] + } + ... + } + + In this case, configuration is forced on the __fuel__ and __power__ options, + that is the corresponding __set-__option____ procedures will be invoked when + the switched object is constructed (see __set-__option____ procedures + documentation below). + + For the __fuel__ option, since there is no initial value, the + __set-__fuel____ procedure is called with the default value (__petrol__) as + argument. For the __power__ option, since the initial value differs from the + default value, the __set-__power____ procedure is called with the initial + value as argument (__50__). + + For the other options, since the initial values (last elements of the option + lists) are identical to their default values, the corresponding + __set-__option____ procedures will not be invoked. It is the programmer's + responsibility to insure that the initial option values are correct. + + - ____ __set-__option____ *this* *value* + + These procedures may be viewed as dynamic virtual functions. There must be + one implementation per supported option, as returned by the __options__ + procedure. For example: + + class car { + ... + proc options {this} { + return [list ... + [list -width {} {}] ] + } + ... + proc set-width {this value} { + ... + } + ... + } + + Since the __-width__ option was listed in the __options__ procedure, a + __set-width__ procedure implementation is provided, which of course would + proceed to set the width of the car (and would modify the looks of a + graphical representation, for example). + + As you add a supported __option__ in the list returned by the __options__ + procedure, the corresponding __set-__option____ procedure may be called as + soon as the switched object is complete, which occurs when the switched + level __complete__ procedure is invoked. For example: + + class car { + proc car {this args} switched {args} { + ... + switched::complete $this + } + ... + proc options {this} { + return [list [list -fuel petrol] [list -length 4.5] [list -power 350] [list -width 1.8] ] + } + proc set-fuel {this value} { + ... + } + proc set-length {this value} { + ... + } + proc set-power {this value} { + ... + } + proc set-width {this value} { + ... + } + } + + new car + + In this case, a new car is created with no options, which causes the car + constructor to be called, which in turns calls the switched level + __complete__ procedure after the car object layer is completely initialized. + At this point, since there are no initial values in any option list in the + options procedure, the __set-fuel__ procedure is called with its default + value of __petrol__ as parameter, followed by the __set-length__ call with + __4.5__ value, __set-power__ with __350__ value and finally with + __set-width__ with __1.8__ as parameter. This is a good way to test the + __set-__option____ procedures when debugging, and when done, just fill-in + the initial option values. + + The switched layer checks that an option is valid (that is, listed in the + __options__ procedure) but obviously does not check the validity of the + value passed to the __set-__option____ procedure, which should throw an + error (for example by using the Tcl error command) if the value is invalid. + + The switched layer also keeps track of the options current values, so that a + __set-__option____ procedure is called only when the corresponding option + value passed as parameter is different from the current value (see + __-option__ data members description). + + - __-option__ + + The __-option__ data member is an options current value. There is one for + each option listed in the options procedure. It is a read-only value which + the switched layer checks against when an option is changed. It is rarely + used at the layer derived from switched, except in the few cases, such as in + the following example: + + ... + proc car::options {this} { + return { + ... + {-manufacturer {} {}} + ... + } + } + + proc car::set-manufacturer {this value} {} + + proc car::printData {this} { + puts "manufacturer: $switched::($this,-manufacturer)" + ... + } + + In this case, the manufacturer's name is stored at the switched layer level + (this is why the set-manufacturer procedure has nothing to do) and later + retrieved in the printData procedure. + + - __complete__ + + The __complete__ data member (not to be confused with the __complete__ + procedure) is a boolean. Its initial value is __false__ and it is set to + __true__ at the very end of the switched __complete__ procedure. It becomes + useful when some options should be set at construction time only and not + dynamically, as the following example shows: + + proc car::set-width {this value} { + if {$switched::($this,complete)} { + error {option -width cannot be set dynamically} + } + ... + } + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *stooop* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[C++](../../../../index.md#c_), [class](../../../../index.md#class), +[object](../../../../index.md#object), [object +oriented](../../../../index.md#object_oriented) + +# CATEGORY + +Programming tools ADDED embedded/md/tcllib/files/modules/string/token.md Index: embedded/md/tcllib/files/modules/string/token.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/string/token.md @@ -0,0 +1,131 @@ + +[//000000001]: # (string::token - Text and string utilities) +[//000000002]: # (Generated from file 'token.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (string::token(n) 1 tcllib "Text and string utilities") + +# NAME + +string::token - Regex based iterative lexing + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.5 +package require string::token ?1? +package require fileutil + +[__::string token text__ *lex* *string*](#1) +[__::string token file__ *lex* *path*](#2) +[__::string token chomp__ *lex* *startvar* *string* *resultvar*](#3) + +# DESCRIPTION + +This package provides commands for regular expression based lexing +(tokenization) of strings. + +The complete set of procedures is described below. + + - __::string token text__ *lex* *string* + + This command takes an ordered dictionary *lex* mapping regular expressions + to labels, and tokenizes the *string* according to this dictionary. + + The result of the command is a list of tokens, where each token is a + 3-element list of label, start- and end-index in the *string*. + + The command will throw an error if it is not able to tokenize the whole + string. + + - __::string token file__ *lex* *path* + + This command is a convenience wrapper around __::string token text__ above, + and __fileutil::cat__, enabling the easy tokenization of whole files. *Note* + that this command loads the file wholly into memory before starting to + process it. + + If the file is too large for this mode of operation a command directly based + on __::string token chomp__ below will be necessary. + + - __::string token chomp__ *lex* *startvar* *string* *resultvar* + + This command is the work horse underlying __::string token text__ above. It + is exposed to enable users to write their own lexers, which, for example may + apply different lexing dictionaries according to some internal state, etc. + + The command takes an ordered dictionary *lex* mapping regular expressions to + labels, a variable *startvar* which indicates where to start lexing in the + input *string*, and a result variable *resultvar* to extend. + + The result of the command is a tri-state numeric code indicating one of + + * __0__ + + No token found. + + * __1__ + + Token found. + + * __2__ + + End of string reached. + + Note that recognition of a token from *lex* is started at the character + index in *startvar*. + + If a token was recognized (status __1__) the command will update the index + in *startvar* to point to the first character of the *string* past the + recognized token, and it will further extend the *resultvar* with a + 3-element list containing the label associated with the regular expression + of the token, and the start- and end-character-indices of the token in + *string*. + + Neither *startvar* nor *resultvar* will be updated if no token is recognized + at all. + + Note that the regular expressions are applied (tested) in the order they are + specified in *lex*, and the first matching pattern stops the process. + Because of this it is recommended to specify the patterns to lex with from + the most specific to the most general. + + Further note that all regex patterns are implicitly prefixed with the + constraint escape __A__ to ensure that a match starts exactly at the + character index found in *startvar*. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *textutil* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[lexing](../../../../index.md#lexing), [regex](../../../../index.md#regex), +[string](../../../../index.md#string), +[tokenization](../../../../index.md#tokenization) + +# CATEGORY + +Text processing ADDED embedded/md/tcllib/files/modules/string/token_shell.md Index: embedded/md/tcllib/files/modules/string/token_shell.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/string/token_shell.md @@ -0,0 +1,161 @@ + +[//000000001]: # (string::token::shell - Text and string utilities) +[//000000002]: # (Generated from file 'token_shell.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (string::token::shell(n) 1.2 tcllib "Text and string utilities") + +# NAME + +string::token::shell - Parsing of shell command line + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.5 +package require string::token::shell ?1.2? +package require string::token ?1? +package require fileutil + +[__::string token shell__ ?__-indices__? ?__-partial__? ?--? *string*](#1) + +# DESCRIPTION + +This package provides a command which parses a line of text using basic +__sh__-syntax into a list of words. + +The complete set of procedures is described below. + + - __::string token shell__ ?__-indices__? ?__-partial__? ?--? *string* + + This command parses the input *string* under the assumption of it following + basic __sh__-syntax. The result of the command is a list of words in the + *string*. An error is thrown if the input does not follow the allowed + syntax. The behaviour can be modified by specifying any of the two options + __-indices__ and __-partial__. + + * __--__ + + When specified option parsing stops at this point. This option is needed + if the input *string* may start with dash. In other words, this is + pretty much required if *string* is user input. + + * __-indices__ + + When specified the output is not a list of words, but a list of 4-tuples + describing the words. Each tuple contains the type of the word, its + start- and end-indices in the input, and the actual text of the word. + + Note that the length of the word as given by the indices can differ from + the length of the word found in the last element of the tuple. The + indices describe the words extent in the input, including delimiters, + intra-word quoting, etc. whereas for the actual text of the word + delimiters are stripped, intra-word quoting decoded, etc. + + The possible token types are + + + __PLAIN__ + + Plain word, not quoted. + + + __D:QUOTED__ + + Word is delimited by double-quotes. + + + __S:QUOTED__ + + Word is delimited by single-quotes. + + + __D:QUOTED:PART__ + + + __S:QUOTED:PART__ + + Like the previous types, but the word has no closing quote, i.e. is + incomplete. These token types can occur if and only if the option + __-partial__ was specified, and only for the last word of the + result. If the option __-partial__ was not specified such incomplete + words cause the command to thrown an error instead. + + * __-partial__ + + When specified the parser will accept an incomplete quoted word (i.e. + without closing quote) at the end of the line as valid instead of + throwing an error. + + The basic shell syntax accepted here are unquoted, single- and double-quoted + words, separated by whitespace. Leading and trailing whitespace are possible + too, and stripped. Shell variables in their various forms are *not* + recognized, nor are sub-shells. As for the recognized forms of words, see + below for the detailed specification. + + * __single-quoted word__ + + A single-quoted word begins with a single-quote character, i.e. __'__ + (ASCII 39) followed by zero or more unicode characters not a + single-quote, and then closed by a single-quote. + + The word must be followed by either the end of the string, or + whitespace. A word cannot directly follow the word. + + * __double-quoted word__ + + A double-quoted word begins with a double-quote character, i.e. __"__ + (ASCII 34) followed by zero or more unicode characters not a + double-quote, and then closed by a double-quote. + + Contrary to single-quoted words a double-quote can be embedded into the + word, by prefacing, i.e. escaping, i.e. quoting it with a backslash + character __\__ (ASCII 92). Similarly a backslash character must be + quoted with itself to be inserted literally. + + * __unquoted word__ + + Unquoted words are not delimited by quotes and thus cannot contain + whitespace or single-quote characters. Double-quote and backslash + characters can be put into unquoted words, by quting them like for + double-quoted words. + + * __whitespace__ + + Whitespace is any unicode space character. This is equivalent to + __string is space__, or the regular expression \\s. + + Whitespace may occur before the first word, or after the last word. + Whitespace must occur between adjacent words. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *textutil* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[bash](../../../../index.md#bash), [lexing](../../../../index.md#lexing), +[parsing](../../../../index.md#parsing), [shell](../../../../index.md#shell), +[string](../../../../index.md#string), +[tokenization](../../../../index.md#tokenization) + +# CATEGORY + +Text processing ADDED embedded/md/tcllib/files/modules/stringprep/stringprep.md Index: embedded/md/tcllib/files/modules/stringprep/stringprep.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/stringprep/stringprep.md @@ -0,0 +1,155 @@ + +[//000000001]: # (stringprep - Preparation of Internationalized Strings) +[//000000002]: # (Generated from file 'stringprep.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (stringprep(n) 1.0.1 tcllib "Preparation of Internationalized Strings") + +# NAME + +stringprep - Implementation of stringprep + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [EXAMPLES](#section3) + + - [REFERENCES](#section4) + + - [AUTHORS](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.3 +package require stringprep 1.0.1 + +[__::stringprep::register__ *profile* ?*-mapping list*? ?*-normalization form*? ?*-prohibited list*? ?*-prohibitedList list*? ?*-prohibitedCommand command*? ?*-prohibitedBidi boolean*?](#1) +[__::stringprep::stringprep__ *profile* *string*](#2) +[__::stringprep::compare__ *profile* *string1* *string2*](#3) + +# DESCRIPTION + +This is an implementation in Tcl of the Preparation of Internationalized Strings +("stringprep"). It allows to define stringprep profiles and use them to prepare +Unicode strings for comparison as defined in RFC-3454. + +# COMMANDS + + - __::stringprep::register__ *profile* ?*-mapping list*? ?*-normalization form*? ?*-prohibited list*? ?*-prohibitedList list*? ?*-prohibitedCommand command*? ?*-prohibitedBidi boolean*? + + Register the __stringprep__ profile named *profile*. Options are the + following. + + Option *-mapping* specifies __stringprep__ mapping tables. This parameter + takes list of tables from appendix B of RFC-3454. The usual list values are + {B.1 B.2} or {B.1 B.3} where B.1 contains characters which commonly map to + nothing, B.3 specifies case folding, and B.2 is used in profiles with + unicode normalization form KC. Defult value is {} which means no mapping. + + Option *-normalization* takes a string and if it is nonempty then it uses as + a name of Unicode normalization form. Any value of "D", "C", "KD" or "KC" + may be used, though RFC-3454 defines only two options: no normalization or + normalization using form KC. + + Option *-prohibited* takes a list of RFC-3454 tables with prohibited + characters. Current version does allow to prohibit either all tables from + C.3 to C.9 or neither of them. An example of this list for RFC-3491 is {A.1 + C.1.2 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9}. + + Option *-prohibitedList* specifies a list of additional prohibited + characters. The list contains not characters themselves but their Unicode + numbers. For example, Nodeprep specification from RFC-3920 forbids the + following codes: {0x22 0x26 0x27 0x2f 0x3a 0x3c 0x3e 0x40} (\" \& \' / : < > + @). + + Option *-prohibitedCommand* specifies a command which is called for every + character code in mapped and normalized string. If the command returns true + then the character is considered prohibited. This option is useful when a + list for *-prohibitedList* is too large. + + Option *-prohibitedBidi* takes boolean value and if it is true then the + bidirectional character processing rules defined in section 6 of RFC-3454 + are used. + + - __::stringprep::stringprep__ *profile* *string* + + Performs __stringprep__ operations defined in profile *profile* to string + *string*. Result is a prepared string or one of the following errors: + *invalid_profile* (profile *profile* is not defined), *prohibited_character* + (string *string* contains a prohibited character) or *prohibited_bidi* + (string *string* contains a prohibited bidirectional sequence). + + - __::stringprep::compare__ *profile* *string1* *string2* + + Compares two unicode strings prepared accordingly to __stringprep__ profile + *profile*. The command returns 0 if prepared strings are equal, -1 if + *string1* is lexicographically less than *string2*, or 1 if *string1* is + lexicographically greater than *string2*. + +# EXAMPLES + +Nameprep profile definition (see RFC-3491): + + ::stringprep::register nameprep -mapping {B.1 B.2} -normalization KC -prohibited {A.1 C.1.2 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9} -prohibitedBidi 1 + +Nodeprep and resourceprep profile definitions (see RFC-3920): + + ::stringprep::register nodeprep -mapping {B.1 B.2} -normalization KC -prohibited {A.1 C.1.1 C.1.2 C.2.1 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9} -prohibitedList {0x22 0x26 0x27 0x2f 0x3a 0x3c 0x3e 0x40} -prohibitedBidi 1 + + ::stringprep::register resourceprep -mapping {B.1} -normalization KC -prohibited {A.1 C.1.2 C.2.1 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9} -prohibitedBidi 1 + +# REFERENCES + + 1. "Preparation of Internationalized Strings ('stringprep')", + ([http://www.ietf.org/rfc/rfc3454.txt](http://www.ietf.org/rfc/rfc3454.txt)) + + 1. "Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)", + ([http://www.ietf.org/rfc/rfc3491.txt](http://www.ietf.org/rfc/rfc3491.txt)) + + 1. "Extensible Messaging and Presence Protocol (XMPP): Core", + ([http://www.ietf.org/rfc/rfc3920.txt](http://www.ietf.org/rfc/rfc3920.txt)) + +# AUTHORS + +Sergei Golovan + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *stringprep* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[unicode(n)](unicode.md) + +# KEYWORDS + +[stringprep](../../../../index.md#stringprep), +[unicode](../../../../index.md#unicode) + +# COPYRIGHT + +Copyright © 2007-2009, Sergei Golovan ADDED embedded/md/tcllib/files/modules/stringprep/stringprep_data.md Index: embedded/md/tcllib/files/modules/stringprep/stringprep_data.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/stringprep/stringprep_data.md @@ -0,0 +1,59 @@ + +[//000000001]: # (stringprep::data - Preparation of Internationalized Strings) +[//000000002]: # (Generated from file 'stringprep_data.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (stringprep::data(n) 1.0.1 tcllib "Preparation of Internationalized Strings") + +# NAME + +stringprep::data - stringprep data tables, generated, internal + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.3 +package require stringprep::data 1.0.1 + +# DESCRIPTION + +The __stringprep::data__ package is a helper for +__[stringprep](stringprep.md)__, providing it with the data tables needed to +perform its functions. It is an *internal* package which should not be accessed +on its own. Because of that it has no publicly documented API either. Its +implementation is generated by a script. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *stringprep* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[stringprep](../../../../index.md#stringprep), +[unicode](../../../../index.md#unicode) + +# COPYRIGHT + +Copyright © 2007-2009, Sergei Golovan ADDED embedded/md/tcllib/files/modules/stringprep/unicode.md Index: embedded/md/tcllib/files/modules/stringprep/unicode.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/stringprep/unicode.md @@ -0,0 +1,122 @@ + +[//000000001]: # (unicode - Unicode normalization) +[//000000002]: # (Generated from file 'unicode.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (unicode(n) 1.0.0 tcllib "Unicode normalization") + +# NAME + +unicode - Implementation of Unicode normalization + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [EXAMPLES](#section3) + + - [REFERENCES](#section4) + + - [AUTHORS](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.3 +package require unicode 1.0 + +[__::unicode::fromstring__ *string*](#1) +[__::unicode::tostring__ *uclist*](#2) +[__::unicode::normalize__ *form* *uclist*](#3) +[__::unicode::normalizeS__ *form* *string*](#4) + +# DESCRIPTION + +This is an implementation in Tcl of the Unicode normalization forms. + +# COMMANDS + + - __::unicode::fromstring__ *string* + + Converts *string* to list of integer Unicode character codes which is used + in __unicode__ for internal string representation. + + - __::unicode::tostring__ *uclist* + + Converts list of integers *uclist* back to Tcl string. + + - __::unicode::normalize__ *form* *uclist* + + Normalizes Unicode characters list *ulist* according to *form* and returns + the normalized list. Form *form* takes one of the following values: *D* + (canonical decomposition), *C* (canonical decomposition, followed by + canonical composition), *KD* (compatibility decomposition), or *KC* + (compatibility decomposition, followed by canonical composition). + + - __::unicode::normalizeS__ *form* *string* + + A shortcut to ::unicode::tostring [unicode::normalize \$form + [::unicode::fromstring \$string]]. Normalizes Tcl string and returns + normalized string. + +# EXAMPLES + + % ::unicode::fromstring "\u0410\u0411\u0412\u0413" + 1040 1041 1042 1043 + % ::unicode::tostring {49 50 51 52 53} + 12345 + % + + % ::unicode::normalize D {7692 775} + 68 803 775 + % ::unicode::normalizeS KD "\u1d2c" + A + % + +# REFERENCES + + 1. "Unicode Standard Annex #15: Unicode Normalization Forms", + ([http://unicode.org/reports/tr15/](http://unicode.org/reports/tr15/)) + +# AUTHORS + +Sergei Golovan + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *stringprep* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[stringprep(n)](stringprep.md) + +# KEYWORDS + +[normalization](../../../../index.md#normalization), +[unicode](../../../../index.md#unicode) + +# COPYRIGHT + +Copyright © 2007, Sergei Golovan ADDED embedded/md/tcllib/files/modules/stringprep/unicode_data.md Index: embedded/md/tcllib/files/modules/stringprep/unicode_data.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/stringprep/unicode_data.md @@ -0,0 +1,59 @@ + +[//000000001]: # (unicode::data - Preparation of Internationalized Strings) +[//000000002]: # (Generated from file 'unicode_data.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (unicode::data(n) 1.0.0 tcllib "Preparation of Internationalized Strings") + +# NAME + +unicode::data - unicode data tables, generated, internal + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.3 +package require unicode::data 1.0.0 + +# DESCRIPTION + +The __unicode::data__ package is a helper for __[unicode](unicode.md)__, +providing it with the data tables needed to perform its functions. It is an +*internal* package which should not be accessed on its own. Because of that it +has no publicly documented API either. Its implementation is generated by a +script. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *stringprep* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[stringprep](../../../../index.md#stringprep), +[unicode](../../../../index.md#unicode) + +# COPYRIGHT + +Copyright © 2007, Sergei Golovan ADDED embedded/md/tcllib/files/modules/struct/disjointset.md Index: embedded/md/tcllib/files/modules/struct/disjointset.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/disjointset.md @@ -0,0 +1,230 @@ + +[//000000001]: # (struct::disjointset - Tcl Data Structures) +[//000000002]: # (Generated from file 'disjointset.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::disjointset(n) 1.1 tcllib "Tcl Data Structures") + +# NAME + +struct::disjointset - Disjoint set data structure + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.6 +package require struct::disjointset ?1.1? + +[__::struct::disjointset__ *disjointsetName*](#1) +[*disjointsetName* *option* ?*arg arg ...*?](#2) +[*disjointsetName* __add-element__ *item*](#3) +[*disjointsetName* __add-partition__ *elements*](#4) +[*disjointsetName* __partitions__](#5) +[*disjointsetName* __num-partitions__](#6) +[*disjointsetName* __equal__ *a* *b*](#7) +[*disjointsetName* __merge__ *a* *b*](#8) +[*disjointsetName* __find__ *e*](#9) +[*disjointsetName* __exemplars__](#10) +[*disjointsetName* __find-exemplar__ *e*](#11) +[*disjointsetName* __destroy__](#12) + +# DESCRIPTION + +This package provides *disjoint sets*. An alternative name for this kind of +structure is *merge-find*. + +Normally when dealing with sets and their elements the question is "Is this +element E contained in this set S?", with both E and S known. + +Here the question is "Which of several sets contains the element E?". I.e. while +the element is known, the set is not, and we wish to find it quickly. It is not +quite the inverse of the original question, but close. Another operation which +is often wanted is that of quickly merging two sets into one, with the result +still fast for finding elements. Hence the alternative term *merge-find* for +this. + +Why now is this named a *disjoint-set* ? Because another way of describing the +whole situation is that we have + + - a finite *[set](../../../../index.md#set)* S, containing + + - a number of *elements* E, split into + + - a set of *partitions* P. The latter term applies, because the intersection + of each pair P, P' of partitions is empty, with the union of all partitions + covering the whole set. + + - An alternative name for the *partitions* would be *equvalence classes*, and + all elements in the same class are considered as equal. + +Here is a pictorial representation of the concepts listed above: + + +-----------------+ The outer lines are the boundaries of the set S. + | / | The inner regions delineated by the skewed lines + | * / * | are the partitions P. The *'s denote the elements + | * / \ | E in the set, each in a single partition, their + |* / \ | equivalence class. + | / * \ | + | / * / | + | * /\ * / | + | / \ / | + | / \/ * | + | / * \ | + | / * \ | + +-----------------+ + +For more information see +[http://en.wikipedia.org/wiki/Disjoint_set_data_structure](http://en.wikipedia.org/wiki/Disjoint_set_data_structure). + +# API + +The package exports a single command, __::struct::disjointset__. All +functionality provided here can be reached through a subcommand of this command. + + - __::struct::disjointset__ *disjointsetName* + + Creates a new disjoint set object with an associated global Tcl command + whose name is *disjointsetName*. This command may be used to invoke various + operations on the disjointset. It has the following general form: + + * *disjointsetName* *option* ?*arg arg ...*? + + The __option__ and the *arg*s determine the exact behavior of the + command. The following commands are possible for disjointset objects: + + - *disjointsetName* __add-element__ *item* + + Creates a new partition in the specified disjoint set, and fills it with the + single item *item*. The command maintains the integrity of the disjoint set, + i.e. it verifies that none of the *elements* are already part of the + disjoint set and throws an error otherwise. + + The result of this method is the empty string. + + This method runs in constant time. + + - *disjointsetName* __add-partition__ *elements* + + Creates a new partition in specified disjoint set, and fills it with the + values found in the set of *elements*. The command maintains the integrity + of the disjoint set, i.e. it verifies that none of the *elements* are + already part of the disjoint set and throws an error otherwise. + + The result of the command is the empty string. + + This method runs in time proportional to the size of *elements*]. + + - *disjointsetName* __partitions__ + + Returns the set of partitions the named disjoint set currently consists of. + The form of the result is a list of lists; the inner lists contain the + elements of the partitions. + + This method runs in time O(N*alpha(N)), where N is the number of elements in + the disjoint set and alpha is the inverse Ackermann function. + + - *disjointsetName* __num-partitions__ + + Returns the number of partitions the named disjoint set currently consists + of. + + This method runs in constant time. + + - *disjointsetName* __equal__ *a* *b* + + Determines if the two elements *a* and *b* of the disjoint set belong to the + same partition. The result of the method is a boolean value, __True__ if the + two elements are contained in the same partition, and __False__ otherwise. + + An error will be thrown if either *a* or *b* are not elements of the + disjoint set. + + This method runs in amortized time O(alpha(N)), where N is the number of + elements in the larger partition and alpha is the inverse Ackermann + function. + + - *disjointsetName* __merge__ *a* *b* + + Determines the partitions the elements *a* and *b* are contained in and + merges them into a single partition. If the two elements were already + contained in the same partition nothing will change. + + The result of the method is the empty string. + + This method runs in amortized time O(alpha(N)), where N is the number of + items in the larger of the partitions being merged. The worst case time is + O(N). + + - *disjointsetName* __find__ *e* + + Returns a list of the members of the partition of the disjoint set which + contains the element *e*. + + This method runs in O(N*alpha(N)) time, where N is the total number of items + in the disjoint set and alpha is the inverse Ackermann function, See + __find-exemplar__ for a faster method, if all that is needed is a unique + identifier for the partition, rather than an enumeration of all its + elements. + + - *disjointsetName* __exemplars__ + + Returns a list containing an exemplar of each partition in the disjoint set. + The exemplar is a member of the partition, chosen arbitrarily. + + This method runs in O(N*alpha(N)) time, where N is the total number of items + in the disjoint set and alpha is the inverse Ackermann function. + + - *disjointsetName* __find-exemplar__ *e* + + Returns the exemplar of the partition of the disjoint set containing the + element *e*. Throws an error if *e* is not found in the disjoint set. The + exemplar is an arbitrarily chosen member of the partition. The only + operation that will change the exemplar of any partition is __merge__. + + This method runs in O(alpha(N)) time, where N is the number of items in the + partition containing E, and alpha is the inverse Ackermann function. + + - *disjointsetName* __destroy__ + + Destroys the disjoint set object and all associated memory. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: disjointset* of +the [Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report +any ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[disjoint set](../../../../index.md#disjoint_set), [equivalence +class](../../../../index.md#equivalence_class), +[find](../../../../index.md#find), [merge +find](../../../../index.md#merge_find), +[partition](../../../../index.md#partition), [partitioned +set](../../../../index.md#partitioned_set), [union](../../../../index.md#union) + +# CATEGORY + +Data structures ADDED embedded/md/tcllib/files/modules/struct/graph.md Index: embedded/md/tcllib/files/modules/struct/graph.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/graph.md @@ -0,0 +1,850 @@ + +[//000000001]: # (struct::graph - Tcl Data Structures) +[//000000002]: # (Generated from file 'graph.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::graph(n) 2.4.1 tcllib "Tcl Data Structures") + +# NAME + +struct::graph - Create and manipulate directed graph objects + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Changes for 2.0](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require struct::graph ?2.4.1? +package require struct::list ?1.5? +package require struct::set ?2.2.3? + +[__::struct::graph__ ?*graphName*? ?__=__|__:=__|__as__|__deserialize__ *source*?](#1) +[__graphName__ *option* ?*arg arg ...*?](#2) +[*graphName* __=__ *sourcegraph*](#3) +[*graphName* __-->__ *destgraph*](#4) +[*graphName* __append__ *key* *value*](#5) +[*graphName* __deserialize__ *serialization*](#6) +[*graphName* __destroy__](#7) +[*graphName* __arc append__ *arc* *key* *value*](#8) +[*graphName* __arc attr__ *key*](#9) +[*graphName* __arc attr__ *key* __-arcs__ *list*](#10) +[*graphName* __arc attr__ *key* __-glob__ *globpattern*](#11) +[*graphName* __arc attr__ *key* __-regexp__ *repattern*](#12) +[*graphName* __arc delete__ *arc* ?*arc* ...?](#13) +[*graphName* __arc exists__ *arc*](#14) +[*graphName* __arc flip__ *arc*](#15) +[*graphName* __arc get__ *arc* *key*](#16) +[*graphName* __arc getall__ *arc* ?*pattern*?](#17) +[*graphName* __arc getunweighted__](#18) +[*graphName* __arc getweight__ *arc*](#19) +[*graphName* __arc keys__ *arc* ?*pattern*?](#20) +[*graphName* __arc keyexists__ *arc* *key*](#21) +[*graphName* __arc insert__ *start* *end* ?*child*?](#22) +[*graphName* __arc lappend__ *arc* *key* *value*](#23) +[*graphName* __arc rename__ *arc* *newname*](#24) +[*graphName* __arc set__ *arc* *key* ?*value*?](#25) +[*graphName* __arc setunweighted__ ?*weight*?](#26) +[*graphName* __arc setweight__ *arc* *weight*](#27) +[*graphName* __arc unsetweight__ *arc*](#28) +[*graphName* __arc hasweight__ *arc*](#29) +[*graphName* __arc source__ *arc*](#30) +[*graphName* __arc target__ *arc*](#31) +[*graphName* __arc nodes__ *arc*](#32) +[*graphName* __arc move-source__ *arc* *newsource*](#33) +[*graphName* __arc move-target__ *arc* *newtarget*](#34) +[*graphName* __arc move__ *arc* *newsource* *newtarget*](#35) +[*graphName* __arc unset__ *arc* *key*](#36) +[*graphName* __arc weights__](#37) +[*graphName* __arcs__ ?-key *key*? ?-value *value*? ?-filter *cmdprefix*? ?-in|-out|-adj|-inner|-embedding *node node...*?](#38) +[*graphName* __lappend__ *key* *value*](#39) +[*graphName* __node append__ *node* *key* *value*](#40) +[*graphName* __node attr__ *key*](#41) +[*graphName* __node attr__ *key* __-nodes__ *list*](#42) +[*graphName* __node attr__ *key* __-glob__ *globpattern*](#43) +[*graphName* __node attr__ *key* __-regexp__ *repattern*](#44) +[*graphName* __node degree__ ?-in|-out? *node*](#45) +[*graphName* __node delete__ *node* ?*node*...?](#46) +[*graphName* __node exists__ *node*](#47) +[*graphName* __node get__ *node* *key*](#48) +[*graphName* __node getall__ *node* ?*pattern*?](#49) +[*graphName* __node keys__ *node* ?*pattern*?](#50) +[*graphName* __node keyexists__ *node* *key*](#51) +[*graphName* __node insert__ ?*node*...?](#52) +[*graphName* __node lappend__ *node* *key* *value*](#53) +[*graphName* __node opposite__ *node* *arc*](#54) +[*graphName* __node rename__ *node* *newname*](#55) +[*graphName* __node set__ *node* *key* ?*value*?](#56) +[*graphName* __node unset__ *node* *key*](#57) +[*graphName* __nodes__ ?-key *key*? ?-value *value*? ?-filter *cmdprefix*? ?-in|-out|-adj|-inner|-embedding *node* *node*...?](#58) +[*graphName* __get__ *key*](#59) +[*graphName* __getall__ ?*pattern*?](#60) +[*graphName* __keys__ ?*pattern*?](#61) +[*graphName* __keyexists__ *key*](#62) +[*graphName* __serialize__ ?*node*...?](#63) +[*graphName* __set__ *key* ?*value*?](#64) +[*graphName* __swap__ *node1* *node2*](#65) +[*graphName* __unset__ *key*](#66) +[*graphName* __walk__ *node* ?-order *order*? ?-type *type*? ?-dir *direction*? -command *cmd*](#67) + +# DESCRIPTION + +A directed graph is a structure containing two collections of elements, called +*nodes* and *arcs* respectively, together with a relation ("connectivity") that +places a general structure upon the nodes and arcs. + +Each arc is connected to two nodes, one of which is called the +*[source](../../../../index.md#source)* and the other the *target*. This imposes +a direction upon the arc, which is said to go from the source to the target. It +is allowed that source and target of an arc are the same node. Such an arc is +called a *[loop](../../../../index.md#loop)*. Whenever a node is either the +source or target of an arc both are said to be +*[adjacent](../../../../index.md#adjacent)*. This extends into a relation +between nodes, i.e. if two nodes are connected through at least one arc they are +said to be *[adjacent](../../../../index.md#adjacent)* too. + +Each node can be the source and target for any number of arcs. The former are +called the *outgoing arcs* of the node, the latter the *incoming arcs* of the +node. The number of arcs in either set is called the *in-degree* resp. the +*out-degree* of the node. + +In addition to maintaining the node and arc relationships, this graph +implementation allows any number of named *attributes* to be associated with the +graph itself, and each node or arc. + +*Note:* The major version of the package +__[struct](../../../../index.md#struct)__ has been changed to version 2.0, due +to backward incompatible changes in the API of this module. Please read the +section [Changes for 2.0](#section2) for a full list of all changes, +incompatible and otherwise. + +*Note:* A C-implementation of the command can be had from the location +[http://www.purl.org/NET/schlenker/tcl/cgraph](http://www.purl.org/NET/schlenker/tcl/cgraph). +See also [http://wiki.tcl.tk/cgraph](http://wiki.tcl.tk/cgraph). This +implementation uses a bit less memory than the tcl version provided here +directly, and is faster. Its support is limited to versions of the package +before 2.0. + +As of version 2.2 of this package a critcl based C implementation is available +from here as well. This implementation however requires Tcl 8.4 to run. + +The main command of the package is: + + - __::struct::graph__ ?*graphName*? ?__=__|__:=__|__as__|__deserialize__ *source*? + + The command creates a new graph object with an associated global Tcl command + whose name is *graphName*. This command may be used to invoke various + operations on the graph. It has the following general form: + + * __graphName__ *option* ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. + + If *graphName* is not specified a unique name will be generated by the + package itself. If a *source* is specified the new graph will be initialized + to it. For the operators __=__, __:=__, and __as__ the *source* argument is + interpreted as the name of another graph object, and the assignment operator + __=__ will be executed. For the operator __deserialize__ the *source* is a + serialized graph object and __deserialize__ will be executed. + + In other words + + ::struct::graph mygraph = b + + is equivalent to + + ::struct::graph mygraph + mygraph = b + + and + + ::struct::graph mygraph deserialize $b + + is equivalent to + + ::struct::graph mygraph + mygraph deserialize $b + +The following commands are possible for graph objects: + + - *graphName* __=__ *sourcegraph* + + This is the *assignment* operator for graph objects. It copies the graph + contained in the graph object *sourcegraph* over the graph data in + *graphName*. The old contents of *graphName* are deleted by this operation. + + This operation is in effect equivalent to + + *graphName* __deserialize__ [*sourcegraph* __serialize__] + + The operation assumes that the *sourcegraph* provides the method + __serialize__ and that this method returns a valid graph serialization. + + - *graphName* __-->__ *destgraph* + + This is the *reverse assignment* operator for graph objects. It copies the + graph contained in the graph object *graphName* over the graph data in the + object *destgraph*. The old contents of *destgraph* are deleted by this + operation. + + This operation is in effect equivalent to + + *destgraph* __deserialize__ [*graphName* __serialize__] + + The operation assumes that the *destgraph* provides the method + __deserialize__ and that this method takes a graph serialization. + + - *graphName* __append__ *key* *value* + + Appends a *value* to one of the keyed values associated with the graph. + Returns the new value given to the attribute *key*. + + - *graphName* __deserialize__ *serialization* + + This is the complement to __serialize__. It replaces the graph data in + *graphName* with the graph described by the *serialization* value. The old + contents of *graphName* are deleted by this operation. + + - *graphName* __destroy__ + + Destroys the graph, including its storage space and associated command. + + - *graphName* __arc append__ *arc* *key* *value* + + Appends a *value* to one of the keyed values associated with an *arc*. + Returns the new value given to the attribute *key*. + + - *graphName* __arc attr__ *key* + + - *graphName* __arc attr__ *key* __-arcs__ *list* + + - *graphName* __arc attr__ *key* __-glob__ *globpattern* + + - *graphName* __arc attr__ *key* __-regexp__ *repattern* + + This method retrieves the value of the attribute named *key*, for all arcs + in the graph (matching the restriction specified via one of the possible + options) and having the specified attribute. + + The result is a dictionary mapping from arc names to the value of attribute + *key* at that arc. Arcs not having the attribute *key*, or not passing a + specified restriction, are not listed in the result. + + The possible restrictions are: + + * __-arcs__ + + The value is a list of arcs. Only the arcs mentioned in this list are + searched for the attribute. + + * __-glob__ + + The value is a glob pattern. Only the arcs in the graph whose names + match this pattern are searched for the attribute. + + * __-regexp__ + + The value is a regular expression. Only the arcs in the graph whose + names match this pattern are searched for the attribute. + + - *graphName* __arc delete__ *arc* ?*arc* ...? + + Remove the specified arcs from the graph. + + - *graphName* __arc exists__ *arc* + + Return true if the specified *arc* exists in the graph. + + - *graphName* __arc flip__ *arc* + + Reverses the direction of the named *arc*, i.e. the source and target nodes + of the arc are exchanged with each other. + + - *graphName* __arc get__ *arc* *key* + + Returns the value associated with the key *key* for the *arc*. + + - *graphName* __arc getall__ *arc* ?*pattern*? + + Returns a dictionary (suitable for use with [__array set__]) for the *arc*. + If the *pattern* is specified only the attributes whose names match the + pattern will be part of the returned dictionary. The pattern is a __glob__ + pattern. + + - *graphName* __arc getunweighted__ + + Returns a list containing the names of all arcs in the graph which have no + weight associated with them. + + - *graphName* __arc getweight__ *arc* + + Returns the weight associated with the *arc*. Throws an error if the arc has + no weight associated with it. + + - *graphName* __arc keys__ *arc* ?*pattern*? + + Returns a list of keys for the *arc*. If the *pattern* is specified only the + attributes whose names match the pattern will be part of the returned list. + The pattern is a __glob__ pattern. + + - *graphName* __arc keyexists__ *arc* *key* + + Return true if the specified *key* exists for the *arc*. + + - *graphName* __arc insert__ *start* *end* ?*child*? + + Insert an arc named *child* into the graph beginning at the node *start* and + ending at the node *end*. If the name of the new arc is not specified the + system will generate a unique name of the form *arc**x*. + + - *graphName* __arc lappend__ *arc* *key* *value* + + Appends a *value* (as a list) to one of the keyed values associated with an + *arc*. Returns the new value given to the attribute *key*. + + - *graphName* __arc rename__ *arc* *newname* + + Renames the arc *arc* to *newname*. An error is thrown if either the arc + does not exist, or a arc with name *newname* does exist. The result of the + command is the new name of the arc. + + - *graphName* __arc set__ *arc* *key* ?*value*? + + Set or get one of the keyed values associated with an arc. An arc may have + any number of keyed values associated with it. If *value* is not specified, + this command returns the current value assigned to the key; if *value* is + specified, this command assigns that value to the key, and returns that + value. + + - *graphName* __arc setunweighted__ ?*weight*? + + Sets the weight of all arcs without a weight to *weight*. Returns the empty + string as its result. If not present *weight* defaults to __0__. + + - *graphName* __arc setweight__ *arc* *weight* + + Sets the weight of the *arc* to *weight*. Returns *weight*. + + - *graphName* __arc unsetweight__ *arc* + + Removes the weight of the *arc*, if present. Does nothing otherwise. Returns + the empty string. + + - *graphName* __arc hasweight__ *arc* + + Determines if the *arc* has a weight associated with it. The result is a + boolean value, __True__ if a weight is defined, and __False__ otherwise. + + - *graphName* __arc source__ *arc* + + Return the node the given *arc* begins at. + + - *graphName* __arc target__ *arc* + + Return the node the given *arc* ends at. + + - *graphName* __arc nodes__ *arc* + + Return the nodes the given *arc* begins and ends at, as a two-element list. + + - *graphName* __arc move-source__ *arc* *newsource* + + Changes the source node of the arc to *newsource*. It can be said that the + arc rotates around its target node. + + - *graphName* __arc move-target__ *arc* *newtarget* + + Changes the target node of the arc to *newtarget*. It can be said that the + arc rotates around its source node. + + - *graphName* __arc move__ *arc* *newsource* *newtarget* + + Changes both source and target nodes of the arc to *newsource*, and + *newtarget* resp. + + - *graphName* __arc unset__ *arc* *key* + + Remove a keyed value from the arc *arc*. The method will do nothing if the + *key* does not exist. + + - *graphName* __arc weights__ + + Returns a dictionary whose keys are the names of all arcs which have a + weight associated with them, and the values are these weights. + + - *graphName* __arcs__ ?-key *key*? ?-value *value*? ?-filter *cmdprefix*? ?-in|-out|-adj|-inner|-embedding *node node...*? + + Returns a list of arcs in the graph. If no restriction is specified a list + containing all arcs is returned. Restrictions can limit the list of returned + arcs based on the nodes that are connected by the arc, on the keyed values + associated with the arc, or both. A general filter command can be used as + well. The restrictions that involve connected nodes take a variable number + of nodes as argument, specified after the name of the restriction itself. + + The restrictions imposed by either __-in__, __-out__, __-adj__, __-inner__, + or __-embedded__ are applied first. Specifying more than one of them is + illegal. + + After that the restrictions set via __-key__ (and __-value__) are applied. + Specifying more than one __-key__ (and __-value__) is illegal. Specifying + __-value__ alone, without __-key__ is illegal as well. + + Any restriction set through __-filter__ is applied last. Specifying more + than one __-filter__ is illegal. + + Coming back to the restrictions based on a set of nodes, the command + recognizes the following switches: + + * __-in__ + + Return a list of all arcs whose target is one of the nodes in the set of + nodes. I.e. it computes the union of all incoming arcs of the nodes in + the set. + + * __-out__ + + Return a list of all arcs whose source is one of the nodes in the set of + nodes. I.e. it computes the union of all outgoing arcs of the nodes in + the set. + + * __-adj__ + + Return a list of all arcs adjacent to at least one of the nodes in the + set. This is the union of the nodes returned by __-in__ and __-out__. + + * __-inner__ + + Return a list of all arcs which are adjacent to two of the nodes in the + set. This is the set of arcs in the subgraph spawned by the specified + nodes. + + * __-embedding__ + + Return a list of all arcs adjacent to exactly one of the nodes in the + set. This is the set of arcs connecting the subgraph spawned by the + specified nodes to the rest of the graph. + + * __-key__ *key* + + Limit the list of arcs that are returned to those arcs that have an + associated key *key*. + + * __-value__ *value* + + This restriction can only be used in combination with __-key__. It + limits the list of arcs that are returned to those arcs whose associated + key *key* has the value *value*. + + * __-filter__ *cmdrefix* + + Limit the list of arcs that are returned to those arcs that pass the + test. The command in *cmdprefix* is called with two arguments, the name + of the graph object, and the name of the arc in question. It is executed + in the context of the caller and has to return a boolean value. Arcs for + which the command returns __false__ are removed from the result list + before it is returned to the caller. + + - *graphName* __lappend__ *key* *value* + + Appends a *value* (as a list) to one of the keyed values associated with the + graph. Returns the new value given to the attribute *key*. + + - *graphName* __node append__ *node* *key* *value* + + Appends a *value* to one of the keyed values associated with an *node*. + Returns the new value given to the attribute *key*. + + - *graphName* __node attr__ *key* + + - *graphName* __node attr__ *key* __-nodes__ *list* + + - *graphName* __node attr__ *key* __-glob__ *globpattern* + + - *graphName* __node attr__ *key* __-regexp__ *repattern* + + This method retrieves the value of the attribute named *key*, for all nodes + in the graph (matching the restriction specified via one of the possible + options) and having the specified attribute. + + The result is a dictionary mapping from node names to the value of attribute + *key* at that node. Nodes not having the attribute *key*, or not passing a + specified restriction, are not listed in the result. + + The possible restrictions are: + + * __-nodes__ + + The value is a list of nodes. Only the nodes mentioned in this list are + searched for the attribute. + + * __-glob__ + + The value is a glob pattern. Only the nodes in the graph whose names + match this pattern are searched for the attribute. + + * __-regexp__ + + The value is a regular expression. Only the nodes in the graph whose + names match this pattern are searched for the attribute. + + - *graphName* __node degree__ ?-in|-out? *node* + + Return the number of arcs adjacent to the specified *node*. If one of the + restrictions __-in__ or __-out__ is given only the incoming resp. outgoing + arcs are counted. + + - *graphName* __node delete__ *node* ?*node*...? + + Remove the specified nodes from the graph. All of the nodes' arcs will be + removed as well to prevent unconnected arcs. + + - *graphName* __node exists__ *node* + + Return true if the specified *node* exists in the graph. + + - *graphName* __node get__ *node* *key* + + Return the value associated with the key *key* for the *node*. + + - *graphName* __node getall__ *node* ?*pattern*? + + Returns a dictionary (suitable for use with [__array set__]) for the *node*. + If the *pattern* is specified only the attributes whose names match the + pattern will be part of the returned dictionary. The pattern is a __glob__ + pattern. + + - *graphName* __node keys__ *node* ?*pattern*? + + Returns a list of keys for the *node*. If the *pattern* is specified only + the attributes whose names match the pattern will be part of the returned + list. The pattern is a __glob__ pattern. + + - *graphName* __node keyexists__ *node* *key* + + Return true if the specified *key* exists for the *node*. + + - *graphName* __node insert__ ?*node*...? + + Insert one or more nodes into the graph. The new nodes have no arcs + connected to them. If no node is specified one node will be inserted, and + the system will generate a unique name of the form *node**x* for it. + + - *graphName* __node lappend__ *node* *key* *value* + + Appends a *value* (as a list) to one of the keyed values associated with an + *node*. Returns the new value given to the attribute *key*. + + - *graphName* __node opposite__ *node* *arc* + + Return the node at the other end of the specified *arc*, which has to be + adjacent to the given *node*. + + - *graphName* __node rename__ *node* *newname* + + Renames the node *node* to *newname*. An error is thrown if either the node + does not exist, or a node with name *newname* does exist. The result of the + command is the new name of the node. + + - *graphName* __node set__ *node* *key* ?*value*? + + Set or get one of the keyed values associated with a node. A node may have + any number of keyed values associated with it. If *value* is not specified, + this command returns the current value assigned to the key; if *value* is + specified, this command assigns that value to the key. + + - *graphName* __node unset__ *node* *key* + + Remove a keyed value from the node *node*. The method will do nothing if the + *key* does not exist. + + - *graphName* __nodes__ ?-key *key*? ?-value *value*? ?-filter *cmdprefix*? ?-in|-out|-adj|-inner|-embedding *node* *node*...? + + Return a list of nodes in the graph. Restrictions can limit the list of + returned nodes based on neighboring nodes, or based on the keyed values + associated with the node. The restrictions that involve neighboring nodes + have a list of nodes as argument, specified after the name of the + restriction itself. + + The possible restrictions are the same as for method __arcs__. The exact + meanings change slightly, as they operate on nodes instead of arcs. The + command recognizes: + + * __-in__ + + Return a list of all nodes with at least one outgoing arc ending in a + node found in the specified set of nodes. Alternatively specified as the + set of source nodes for the __-in__ arcs of the node set. The *incoming + neighbours*. + + * __-out__ + + Return a list of all nodes with at least one incoming arc starting in a + node found in the specified set of nodes. Alternatively specified as the + set of target nodes for the __-out__ arcs of the node set. The *outgoing + neighbours*. + + * __-adj__ + + This is the union of the nodes returned by __-in__ and __-out__. The + *neighbours*. + + * __-inner__ + + The set of neighbours (see __-adj__ above) which are also in the set of + nodes. I.e. the intersection between the set of nodes and the neighbours + per __-adj__. + + * __-embedding__ + + The set of neighbours (see __-adj__ above) which are not in the set of + nodes. I.e. the difference between the neighbours as per __-adj__, and + the set of nodes. + + * __-key__ *key* + + Limit the list of nodes that are returned to those nodes that have an + associated key *key*. + + * __-value__ *value* + + This restriction can only be used in combination with __-key__. It + limits the list of nodes that are returned to those nodes whose + associated key *key* has the value *value*. + + * __-filter__ *cmdrefix* + + Limit the list of nodes that are returned to those nodes that pass the + test. The command in *cmdprefix* is called with two arguments, the name + of the graph object, and the name of the node in question. It is + executed in the context of the caller and has to return a boolean value. + Nodes for which the command returns __false__ are removed from the + result list before it is returned to the caller. + + - *graphName* __get__ *key* + + Return the value associated with the key *key* for the graph. + + - *graphName* __getall__ ?*pattern*? + + Returns a dictionary (suitable for use with [__array set__]) for the whole + graph. If the *pattern* is specified only the attributes whose names match + the pattern will be part of the returned dictionary. The pattern is a + __glob__ pattern. + + - *graphName* __keys__ ?*pattern*? + + Returns a list of keys for the whole graph. If the *pattern* is specified + only the attributes whose names match the pattern will be part of the + returned list. The pattern is a __glob__ pattern. + + - *graphName* __keyexists__ *key* + + Return true if the specified *key* exists for the whole graph. + + - *graphName* __serialize__ ?*node*...? + + This method serializes the sub-graph spanned up by the *node*s. In other + words it returns a tcl value completely describing that graph. If no nodes + are specified the whole graph will be serialized. This allows, for example, + the transfer of graph objects (or parts thereof) over arbitrary channels, + persistence, etc. This method is also the basis for both the copy + constructor and the assignment operator. + + The result of this method has to be semantically identical over all + implementations of the graph interface. This is what will enable us to copy + graph data between different implementations of the same interface. + + The result is a list containing a multiple of three items, plus one! In + other words, '[llength $serial] % 3 == 1'. Valid values include 1, 4, 7, ... + + The last element of the list is a dictionary containing the attributes + associated with the whole graph. Regarding the other elements; each triple + consists of + + The name of the node to be described, + + A dictionary containing the attributes associated with the node, + + And a list describing all the arcs starting at that node. + + The elements of the arc list are lists containing three or four elements + each, i.e. + + The name of the arc described by the element, + + A reference to the destination node of the arc. This reference is an integer + number given the index of that node in the main serialization list. As that + it is greater than or equal to zero, less than the length of the + serialization, and a multiple of three. *Note:* For internal consistency no + arc name may be used twice, whether in the same node, or at some other node. + This is a global consistency requirement for the serialization. + + And a dictionary containing the attributes associated with the arc. + + The weight associated with the arc. This value is optional. Its non-presence + means that the arc in question has no weight associated with it. + + *Note:* This information is new, compared to the serialization of + __[graph](../../../../index.md#graph)__ 2.3 and earlier. By making it an + optional element the new format is maximally compatible with the old. This + means that any graph not using weights will generate a serialization which + is still understood by the older graph package. A serialization will not be + understood any longer by the older packages if, and only if the graph it was + generated from actually has arcs with weights. + + For all attribute dictionaries they keys are the names of the attributes, + and the values are the values for each name. + + *Note:* The order of the nodes in the serialization has no relevance, nor + has the order of the arcs per node. + + # A possible serialization for the graph structure + # + # d -----> %2 + # / ^ \\ + # / / \\ + # / b \\ + # / / \\ + # %1 <- a - %0 e + # ^ \\ / + # \\ c / + # \\ \\ / + # \\ v v + # f ------ %3 + # is + # + # %3 {} {{f 6 {}}} %0 {} {{a 6 {}} {b 9 {}} {c 0 {}}} %1 {} {{d 9 {}}} %2 {} {{e 0 {}}} {} + # + # This assumes that the graph has neither attribute data nor weighted arcs. + + - *graphName* __set__ *key* ?*value*? + + Set or get one of the keyed values associated with a graph. A graph may have + any number of keyed values associated with it. If *value* is not specified, + this command returns the current value assigned to the key; if *value* is + specified, this command assigns that value to the key. + + - *graphName* __swap__ *node1* *node2* + + Swap the position of *node1* and *node2* in the graph. + + - *graphName* __unset__ *key* + + Remove a keyed value from the graph. The method will do nothing if the *key* + does not exist. + + - *graphName* __walk__ *node* ?-order *order*? ?-type *type*? ?-dir *direction*? -command *cmd* + + Perform a breadth-first or depth-first walk of the graph starting at the + node *node* going in either the direction of outgoing or opposite to the + incoming arcs. + + The type of walk, breadth-first or depth-first, is determined by the value + of *type*; __bfs__ indicates breadth-first, __dfs__ indicates depth-first. + Depth-first is the default. + + The order of the walk, pre-order, post-order or both-order is determined by + the value of *order*; __pre__ indicates pre-order, __post__ indicates + post-order, __both__ indicates both-order. Pre-order is the default. + Pre-order walking means that a node is visited before any of its neighbors + (as defined by the *direction*, see below). Post-order walking means that a + parent is visited after any of its neighbors. Both-order walking means that + a node is visited before *and* after any of its neighbors. The combination + of a breadth-first walk with post- or both-order is illegal. + + The direction of the walk is determined by the value of *dir*; __backward__ + indicates the direction opposite to the incoming arcs, __forward__ indicates + the direction of the outgoing arcs. + + As the walk progresses, the command *cmd* will be evaluated at each node, + with the mode of the call (__enter__ or __leave__) and values *graphName* + and the name of the current node appended. For a pre-order walk, all nodes + are __enter__ed, for a post-order all nodes are left. In a both-order walk + the first visit of a node __enter__s it, the second visit __leave__s it. + +# Changes for 2.0 + +The following noteworthy changes have occurred: + + 1. The API for accessing attributes and their values has been simplified. + + All functionality regarding the default attribute "data" has been removed. + This default attribute does not exist anymore. All accesses to attributes + have to specify the name of the attribute in question. This backward + *incompatible* change allowed us to simplify the signature of all methods + handling attributes. + + Especially the flag __-key__ is not required anymore, even more, its use is + now forbidden. Please read the documentation for the arc and node methods + __set__, __get__, __getall__, __unset__, __append__, __lappend__, + __keyexists__ and __keys__ for a description of the new API's. + + 1. The methods __keys__ and __getall__ now take an optional pattern argument + and will return only attribute data for keys matching this pattern. + + 1. Arcs and nodes can now be renamed. See the documentation for the methods + __arc rename__ and __node rename__. + + 1. The structure has been extended with API's for the serialization and + deserialization of graph objects, and a number of operations based on them + (graph assignment, copy construction). + + Please read the documentation for the methods __serialize__, + __deserialize__, __=__, and __-->__, and the documentation on the + construction of graph objects. + + Beyond the copying of whole graph objects these new API's also enable the + transfer of graph objects over arbitrary channels and for easy persistence. + + 1. A new method, __attr__, was added to both __arc__ and __node__ allowing the + query and retrieval of attribute data without regard to arc and node + relationships. + + 1. Both methods __arcs__ and __nodes__ have been extended with the ability to + select arcs and nodes based on an arbitrary filtering criterium. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: graph* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[adjacent](../../../../index.md#adjacent), [arc](../../../../index.md#arc), +[cgraph](../../../../index.md#cgraph), [degree](../../../../index.md#degree), +[edge](../../../../index.md#edge), [graph](../../../../index.md#graph), +[loop](../../../../index.md#loop), [neighbour](../../../../index.md#neighbour), +[node](../../../../index.md#node), +[serialization](../../../../index.md#serialization), +[subgraph](../../../../index.md#subgraph), [vertex](../../../../index.md#vertex) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2002-2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/struct/graph1.md Index: embedded/md/tcllib/files/modules/struct/graph1.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/graph1.md @@ -0,0 +1,397 @@ + +[//000000001]: # (struct::graph_v1 - Tcl Data Structures) +[//000000002]: # (Generated from file 'graph1.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::graph_v1(n) 1.2.1 tcllib "Tcl Data Structures") + +# NAME + +struct::graph_v1 - Create and manipulate directed graph objects + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require struct::graph ?1.2.1? + +[__graphName__ *option* ?*arg arg ...*?](#1) +[*graphName* __destroy__](#2) +[*graphName* __arc append__ *arc* ?-key *key*? *value*](#3) +[*graphName* __arc delete__ *arc* ?*arc* ...?](#4) +[*graphName* __arc exists__ *arc*](#5) +[*graphName* __arc get__ *arc* ?-key *key*?](#6) +[*graphName* __arc getall__ *arc*](#7) +[*graphName* __arc keys__ *arc*](#8) +[*graphName* __arc keyexists__ *arc* ?-key *key*?](#9) +[*graphName* __arc insert__ *start* *end* ?*child*?](#10) +[*graphName* __arc lappend__ *arc* ?-key *key*? *value*](#11) +[*graphName* __arc set__ *arc* ?-key *key*? ?*value*?](#12) +[*graphName* __arc source__ *arc*](#13) +[*graphName* __arc target__ *arc*](#14) +[*graphName* __arc unset__ *arc* ?-key *key*?](#15) +[*graphName* __arcs__ ?-key *key*? ?-value *value*? ?-in|-out|-adj|-inner|-embedding *nodelist*?](#16) +[*graphName* __node append__ *node* ?-key *key*? *value*](#17) +[*graphName* __node degree__ ?-in|-out? *node*](#18) +[*graphName* __node delete__ *node* ?*node* ...?](#19) +[*graphName* __node exists__ *node*](#20) +[*graphName* __node get__ *node* ?-key *key*?](#21) +[*graphName* __node getall__ *node*](#22) +[*graphName* __node keys__ *node*](#23) +[*graphName* __node keyexists__ *node* ?-key *key*?](#24) +[*graphName* __node insert__ ?*child*?](#25) +[*graphName* __node lappend__ *node* ?-key *key*? *value*](#26) +[*graphName* __node opposite__ *node* *arc*](#27) +[*graphName* __node set__ *node* ?-key *key*? ?*value*?](#28) +[*graphName* __node unset__ *node* ?-key *key*?](#29) +[*graphName* __nodes__ ?-key *key*? ?-value *value*? ?-in|-out|-adj|-inner|-embedding *nodelist*?](#30) +[*graphName* __get__ ?-key *key*?](#31) +[*graphName* __getall__](#32) +[*graphName* __keys__](#33) +[*graphName* __keyexists__ ?-key *key*?](#34) +[*graphName* __set__ ?-key *key*? ?*value*?](#35) +[*graphName* __swap__ *node1* *node2*](#36) +[*graphName* __unset__ ?-key *key*?](#37) +[*graphName* __walk__ *node* ?-order *order*? ?-type *type*? ?-dir *direction*? -command *cmd*](#38) + +# DESCRIPTION + +The __::struct::graph__ command creates a new graph object with an associated +global Tcl command whose name is *graphName*. This command may be used to invoke +various operations on the graph. It has the following general form: + + - __graphName__ *option* ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. + +A directed graph is a structure containing two collections of elements, called +*nodes* and *arcs* respectively, together with a relation ("connectivity") that +places a general structure upon the nodes and arcs. + +Each arc is connected to two nodes, one of which is called the *source* and the +other the *target*. This imposes a direction upon the arc, which is said to go +from the source to the target. It is allowed that source and target of an arc +are the same node. Such an arc is called a *loop*. Whenever a node is source or +target of an arc both are said to be *adjacent*. This extends into a relation +between nodes, i.e. if two nodes are connected through at least one arc they are +said to be *adjacent* too. + +Each node can be the source and target for any number of arcs. The former are +called the *outgoing arcs* of the node, the latter the *incoming arcs* of the +node. The number of edges in either set is called the *in-* resp. the +*out-degree* of the node. + +In addition to maintaining the node and arc relationships, this graph +implementation allows any number of keyed values to be associated with each node +and arc. + +The following commands are possible for graph objects: + + - *graphName* __destroy__ + + Destroy the graph, including its storage space and associated command. + + - *graphName* __arc append__ *arc* ?-key *key*? *value* + + Appends a *value* to one of the keyed values associated with an *arc*. If no + *key* is specified, the key __data__ is assumed. + + - *graphName* __arc delete__ *arc* ?*arc* ...? + + Remove the specified arcs from the graph. + + - *graphName* __arc exists__ *arc* + + Return true if the specified *arc* exists in the graph. + + - *graphName* __arc get__ *arc* ?-key *key*? + + Return the value associated with the key *key* for the *arc*. If no key is + specified, the key __data__ is assumed. + + - *graphName* __arc getall__ *arc* + + Returns a serialized list of key/value pairs (suitable for use with [__array + set__]) for the *arc*. + + - *graphName* __arc keys__ *arc* + + Returns a list of keys for the *arc*. + + - *graphName* __arc keyexists__ *arc* ?-key *key*? + + Return true if the specified *key* exists for the *arc*. If no *key* is + specified, the key __data__ is assumed. + + - *graphName* __arc insert__ *start* *end* ?*child*? + + Insert an arc named *child* into the graph beginning at the node *start* and + ending at the node *end*. If the name of the new arc is not specified the + system will generate a unique name of the form *arc**x*. + + - *graphName* __arc lappend__ *arc* ?-key *key*? *value* + + Appends a *value* (as a list) to one of the keyed values associated with an + *arc*. If no *key* is specified, the key __data__ is assumed. + + - *graphName* __arc set__ *arc* ?-key *key*? ?*value*? + + Set or get one of the keyed values associated with an arc. If no key is + specified, the key __data__ is assumed. Each arc that is added to a graph + has the empty string assigned to the key __data__ automatically. An arc may + have any number of keyed values associated with it. If *value* is not + specified, this command returns the current value assigned to the key; if + *value* is specified, this command assigns that value to the key. + + - *graphName* __arc source__ *arc* + + Return the node the given *arc* begins at. + + - *graphName* __arc target__ *arc* + + Return the node the given *arc* ends at. + + - *graphName* __arc unset__ *arc* ?-key *key*? + + Remove a keyed value from the arc *arc*. If no key is specified, the key + __data__ is assumed. + + - *graphName* __arcs__ ?-key *key*? ?-value *value*? ?-in|-out|-adj|-inner|-embedding *nodelist*? + + Return a list of arcs in the graph. If no restriction is specified a list + containing all arcs is returned. Restrictions can limit the list of returned + arcs based on the nodes that are connected by the arc, on the keyed values + associated with the arc, or both. The restrictions that involve connected + nodes have a list of nodes as argument, specified after the name of the + restriction itself. + + * __-in__ + + Return a list of all arcs whose target is one of the nodes in the + *nodelist*. + + * __-out__ + + Return a list of all arcs whose source is one of the nodes in the + *nodelist*. + + * __-adj__ + + Return a list of all arcs adjacent to at least one of the nodes in the + *nodelist*. This is the union of the nodes returned by __-in__ and + __-out__. + + * __-inner__ + + Return a list of all arcs adjacent to two of the nodes in the + *nodelist*. This is the set of arcs in the subgraph spawned by the + specified nodes. + + * __-embedding__ + + Return a list of all arcs adjacent to exactly one of the nodes in the + *nodelist*. This is the set of arcs connecting the subgraph spawned by + the specified nodes to the rest of the graph. + + * __-key__ *key* + + Limit the list of arcs that are returned to those arcs that have an + associated key *key*. + + * __-value__ *value* + + This restriction can only be used in combination with __-key__. It + limits the list of arcs that are returned to those arcs whose associated + key *key* has the value *value*. + + The restrictions imposed by either __-in__, __-out__, __-adj__, __-inner__, + or __-embedded__ are applied first. Specifying more than one of them is + illegal. At last the restrictions set via __-key__ (and __-value__) are + applied. Specifying more than one __-key__ (and __-value__) is illegal. + + - *graphName* __node append__ *node* ?-key *key*? *value* + + Appends a *value* to one of the keyed values associated with an *node*. If + no *key* is specified, the key __data__ is assumed. + + - *graphName* __node degree__ ?-in|-out? *node* + + Return the number of arcs adjacent to the specified *node*. If one of the + restrictions __-in__ or __-out__ is given only the incoming resp. outgoing + arcs are counted. + + - *graphName* __node delete__ *node* ?*node* ...? + + Remove the specified nodes from the graph. All of the nodes' arcs will be + removed as well to prevent unconnected arcs. + + - *graphName* __node exists__ *node* + + Return true if the specified *node* exists in the graph. + + - *graphName* __node get__ *node* ?-key *key*? + + Return the value associated with the key *key* for the *node*. If no key is + specified, the key __data__ is assumed. + + - *graphName* __node getall__ *node* + + Returns a serialized list of key/value pairs (suitable for use with [__array + set__]) for the *node*. + + - *graphName* __node keys__ *node* + + Returns a list of keys for the *node*. + + - *graphName* __node keyexists__ *node* ?-key *key*? + + Return true if the specified *key* exists for the *node*. If no *key* is + specified, the key __data__ is assumed. + + - *graphName* __node insert__ ?*child*? + + Insert a node named *child* into the graph. The nodes has no arcs connected + to it. If the name of the new child is not specified the system will + generate a unique name of the form *node**x*. + + - *graphName* __node lappend__ *node* ?-key *key*? *value* + + Appends a *value* (as a list) to one of the keyed values associated with an + *node*. If no *key* is specified, the key __data__ is assumed. + + - *graphName* __node opposite__ *node* *arc* + + Return the node at the other end of the specified *arc*, which has to be + adjacent to the given *node*. + + - *graphName* __node set__ *node* ?-key *key*? ?*value*? + + Set or get one of the keyed values associated with a node. If no key is + specified, the key __data__ is assumed. Each node that is added to a graph + has the empty string assigned to the key __data__ automatically. A node may + have any number of keyed values associated with it. If *value* is not + specified, this command returns the current value assigned to the key; if + *value* is specified, this command assigns that value to the key. + + - *graphName* __node unset__ *node* ?-key *key*? + + Remove a keyed value from the node *node*. If no key is specified, the key + __data__ is assumed. + + - *graphName* __nodes__ ?-key *key*? ?-value *value*? ?-in|-out|-adj|-inner|-embedding *nodelist*? + + Return a list of nodes in the graph. Restrictions can limit the list of + returned nodes based on neighboring nodes, or based on the keyed values + associated with the node. The restrictions that involve neighboring nodes + have a list of nodes as argument, specified after the name of the + restriction itself. + + The possible restrictions are the same as for method __arcs__. The set of + nodes to return is computed as the union of all source and target nodes for + all the arcs satisfying the restriction as defined for __arcs__. + + - *graphName* __get__ ?-key *key*? + + Return the value associated with the key *key* for the graph. If no key is + specified, the key __data__ is assumed. + + - *graphName* __getall__ + + Returns a serialized list of key/value pairs (suitable for use with [__array + set__]) for the whole graph. + + - *graphName* __keys__ + + Returns a list of keys for the whole graph. + + - *graphName* __keyexists__ ?-key *key*? + + Return true if the specified *key* exists for the whole graph. If no *key* + is specified, the key __data__ is assumed. + + - *graphName* __set__ ?-key *key*? ?*value*? + + Set or get one of the keyed values associated with a graph. If no key is + specified, the key __data__ is assumed. Each graph has the empty string + assigned to the key __data__ automatically. A graph may have any number of + keyed values associated with it. If *value* is not specified, this command + returns the current value assigned to the key; if *value* is specified, this + command assigns that value to the key. + + - *graphName* __swap__ *node1* *node2* + + Swap the position of *node1* and *node2* in the graph. + + - *graphName* __unset__ ?-key *key*? + + Remove a keyed value from the graph. If no key is specified, the key + __data__ is assumed. + + - *graphName* __walk__ *node* ?-order *order*? ?-type *type*? ?-dir *direction*? -command *cmd* + + Perform a breadth-first or depth-first walk of the graph starting at the + node *node* going in either the direction of outgoing or opposite to the + incoming arcs. + + The type of walk, breadth-first or depth-first, is determined by the value + of *type*; __bfs__ indicates breadth-first, __dfs__ indicates depth-first. + Depth-first is the default. + + The order of the walk, pre-order, post-order or both-order is determined by + the value of *order*; __pre__ indicates pre-order, __post__ indicates + post-order, __both__ indicates both-order. Pre-order is the default. + Pre-order walking means that a node is visited before any of its neighbors + (as defined by the *direction*, see below). Post-order walking means that a + parent is visited after any of its neighbors. Both-order walking means that + a node is visited before *and* after any of its neighbors. The combination + of a bread-first walk with post- or both-order is illegal. + + The direction of the walk is determined by the value of *dir*; __backward__ + indicates the direction opposite to the incoming arcs, __forward__ indicates + the direction of the outgoing arcs. + + As the walk progresses, the command *cmd* will be evaluated at each node, + with the mode of the call (__enter__ or __leave__) and values *graphName* + and the name of the current node appended. For a pre-order walk, all nodes + are __enter__ed, for a post-order all nodes are left. In a both-order walk + the first visit of a node __enter__s it, the second visit __leave__s it. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: graph* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[cgraph](../../../../index.md#cgraph), [graph](../../../../index.md#graph) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2002 Andreas Kupries ADDED embedded/md/tcllib/files/modules/struct/graphops.md Index: embedded/md/tcllib/files/modules/struct/graphops.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/graphops.md @@ -0,0 +1,1423 @@ + +[//000000001]: # (struct::graph::op - Tcl Data Structures) +[//000000002]: # (Generated from file 'graphops.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::graph::op(n) 0.11.3 tcllib "Tcl Data Structures") + +# NAME + +struct::graph::op - Operation for (un)directed graph objects + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Operations](#section2) + + - [Background theory and terms](#section3) + + - [Shortest Path Problem](#subsection1) + + - [Travelling Salesman Problem](#subsection2) + + - [Matching Problem](#subsection3) + + - [Cut Problems](#subsection4) + + - [K-Center Problem](#subsection5) + + - [Flow Problems](#subsection6) + + - [Approximation algorithm](#subsection7) + + - [References](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require struct::graph::op ?0.11.3? + +[__struct::graph::op::toAdjacencyMatrix__ *g*](#1) +[__struct::graph::op::toAdjacencyList__ *G* ?*options*...?](#2) +[__struct::graph::op::kruskal__ *g*](#3) +[__struct::graph::op::prim__ *g*](#4) +[__struct::graph::op::isBipartite?__ *g* ?*bipartvar*?](#5) +[__struct::graph::op::tarjan__ *g*](#6) +[__struct::graph::op::connectedComponents__ *g*](#7) +[__struct::graph::op::connectedComponentOf__ *g* *n*](#8) +[__struct::graph::op::isConnected?__ *g*](#9) +[__struct::graph::op::isCutVertex?__ *g* *n*](#10) +[__struct::graph::op::isBridge?__ *g* *a*](#11) +[__struct::graph::op::isEulerian?__ *g* ?*tourvar*?](#12) +[__struct::graph::op::isSemiEulerian?__ *g* ?*pathvar*?](#13) +[__struct::graph::op::dijkstra__ *g* *start* ?*options*...?](#14) +[__struct::graph::op::distance__ *g* *origin* *destination* ?*options*...?](#15) +[__struct::graph::op::eccentricity__ *g* *n* ?*options*...?](#16) +[__struct::graph::op::radius__ *g* ?*options*...?](#17) +[__struct::graph::op::diameter__ *g* ?*options*...?](#18) +[__struct::graph::op::BellmanFord__ *G* *startnode*](#19) +[__struct::graph::op::Johnsons__ *G* ?*options*...?](#20) +[__struct::graph::op::FloydWarshall__ *G*](#21) +[__struct::graph::op::MetricTravellingSalesman__ *G*](#22) +[__struct::graph::op::Christofides__ *G*](#23) +[__struct::graph::op::GreedyMaxMatching__ *G*](#24) +[__struct::graph::op::MaxCut__ *G* *U* *V*](#25) +[__struct::graph::op::UnweightedKCenter__ *G* *k*](#26) +[__struct::graph::op::WeightedKCenter__ *G* *nodeWeights* *W*](#27) +[__struct::graph::op::GreedyMaxIndependentSet__ *G*](#28) +[__struct::graph::op::GreedyWeightedMaxIndependentSet__ *G* *nodeWeights*](#29) +[__struct::graph::op::VerticesCover__ *G*](#30) +[__struct::graph::op::EdmondsKarp__ *G* *s* *t*](#31) +[__struct::graph::op::BusackerGowen__ *G* *desiredFlow* *s* *t*](#32) +[__struct::graph::op::ShortestsPathsByBFS__ *G* *s* *outputFormat*](#33) +[__struct::graph::op::BFS__ *G* *s* ?*outputFormat*...?](#34) +[__struct::graph::op::MinimumDiameterSpanningTree__ *G*](#35) +[__struct::graph::op::MinimumDegreeSpanningTree__ *G*](#36) +[__struct::graph::op::MaximumFlowByDinic__ *G* *s* *t* *blockingFlowAlg*](#37) +[__struct::graph::op::BlockingFlowByDinic__ *G* *s* *t*](#38) +[__struct::graph::op::BlockingFlowByMKM__ *G* *s* *t*](#39) +[__struct::graph::op::createResidualGraph__ *G* *f*](#40) +[__struct::graph::op::createAugmentingNetwork__ *G* *f* *path*](#41) +[__struct::graph::op::createLevelGraph__ *Gf* *s*](#42) +[__struct::graph::op::TSPLocalSearching__ *G* *C*](#43) +[__struct::graph::op::TSPLocalSearching3Approx__ *G* *C*](#44) +[__struct::graph::op::createSquaredGraph__ *G*](#45) +[__struct::graph::op::createCompleteGraph__ *G* *originalEdges*](#46) + +# DESCRIPTION + +The package described by this document, __struct::graph::op__, is a companion to +the package __[struct::graph](graph.md)__. It provides a series of common +operations and algorithms applicable to (un)directed graphs. + +Despite being a companion the package is not directly dependent on +__[struct::graph](graph.md)__, only on the API defined by that package. I.e. the +operations of this package can be applied to any and all graph objects which +provide the same API as the objects created through +__[struct::graph](graph.md)__. + +# Operations + + - __struct::graph::op::toAdjacencyMatrix__ *g* + + This command takes the graph *g* and returns a nested list containing the + adjacency matrix of *g*. + + The elements of the outer list are the rows of the matrix, the inner + elements are the column values in each row. The matrix has "__n__+1" rows + and columns, with the first row and column (index 0) containing the name of + the node the row/column is for. All other elements are boolean values, + __True__ if there is an arc between the 2 nodes of the respective row and + column, and __False__ otherwise. + + Note that the matrix is symmetric. It does not represent the directionality + of arcs, only their presence between nodes. It is also unable to represent + parallel arcs in *g*. + + - __struct::graph::op::toAdjacencyList__ *G* ?*options*...? + + Procedure creates for input graph *G*, it's representation as *[Adjacency + List](../../../../index.md#adjacency_list)*. It handles both directed and + undirected graphs (default is undirected). It returns dictionary that for + each node (key) returns list of nodes adjacent to it. When considering + weighted version, for each adjacent node there is also weight of the edge + included. + + * Arguments: + + + Graph object *G* (input) + + A graph to convert into an *[Adjacency + List](../../../../index.md#adjacency_list)*. + + * Options: + + + __-directed__ + + By default *G* is operated as if it were an *Undirected graph*. + Using this option tells the command to handle *G* as the directed + graph it is. + + + __-weights__ + + By default any weight information the graph *G* may have is ignored. + Using this option tells the command to put weight information into + the result. In that case it is expected that all arcs have a proper + weight, and an error is thrown if that is not the case. + + - __struct::graph::op::kruskal__ *g* + + This command takes the graph *g* and returns a list containing the names of + the arcs in *g* which span up a minimum weight spanning tree (MST), or, in + the case of an un-connected graph, a minimum weight spanning forest (except + for the 1-vertex components). Kruskal's algorithm is used to compute the + tree or forest. This algorithm has a time complexity of *O(E*log E)* or + *O(E* log V)*, where *V* is the number of vertices and + *[E](../../../../index.md#e)* is the number of edges in graph *g*. + + The command will throw an error if one or more arcs in *g* have no weight + associated with them. + + A note regarding the result, the command refrains from explicitly listing + the nodes of the MST as this information is implicitly provided in the arcs + already. + + - __struct::graph::op::prim__ *g* + + This command takes the graph *g* and returns a list containing the names of + the arcs in *g* which span up a minimum weight spanning tree (MST), or, in + the case of an un-connected graph, a minimum weight spanning forest (except + for the 1-vertex components). Prim's algorithm is used to compute the tree + or forest. This algorithm has a time complexity between *O(E+V*log V)* and + *O(V*V)*, depending on the implementation (Fibonacci heap + Adjacency list + versus Adjacency Matrix). As usual *V* is the number of vertices and + *[E](../../../../index.md#e)* the number of edges in graph *g*. + + The command will throw an error if one or more arcs in *g* have no weight + associated with them. + + A note regarding the result, the command refrains from explicitly listing + the nodes of the MST as this information is implicitly provided in the arcs + already. + + - __struct::graph::op::isBipartite?__ *g* ?*bipartvar*? + + This command takes the graph *g* and returns a boolean value indicating + whether it is bipartite (__true__) or not (__false__). If the variable + *bipartvar* is specified the two partitions of the graph are there as a + list, if, and only if the graph is bipartit. If it is not the variable, if + specified, is not touched. + + - __struct::graph::op::tarjan__ *g* + + This command computes the set of *strongly connected* components (SCCs) of + the graph *g*. The result of the command is a list of sets, each of which + contains the nodes for one of the SCCs of *g*. The union of all SCCs covers + the whole graph, and no two SCCs intersect with each other. + + The graph *g* is *acyclic* if all SCCs in the result contain only a single + node. The graph *g* is *strongly connected* if the result contains only a + single SCC containing all nodes of *g*. + + - __struct::graph::op::connectedComponents__ *g* + + This command computes the set of *connected* components (CCs) of the graph + *g*. The result of the command is a list of sets, each of which contains the + nodes for one of the CCs of *g*. The union of all CCs covers the whole + graph, and no two CCs intersect with each other. + + The graph *g* is *connected* if the result contains only a single SCC + containing all nodes of *g*. + + - __struct::graph::op::connectedComponentOf__ *g* *n* + + This command computes the *connected* component (CC) of the graph *g* + containing the node *n*. The result of the command is a sets which contains + the nodes for the CC of *n* in *g*. + + The command will throw an error if *n* is not a node of the graph *g*. + + - __struct::graph::op::isConnected?__ *g* + + This is a convenience command determining whether the graph *g* is + *connected* or not. The result is a boolean value, __true__ if the graph is + connected, and __false__ otherwise. + + - __struct::graph::op::isCutVertex?__ *g* *n* + + This command determines whether the node *n* in the graph *g* is a *[cut + vertex](../../../../index.md#cut_vertex)* (aka *[articulation + point](../../../../index.md#articulation_point)*). The result is a boolean + value, __true__ if the node is a cut vertex, and __false__ otherwise. + + The command will throw an error if *n* is not a node of the graph *g*. + + - __struct::graph::op::isBridge?__ *g* *a* + + This command determines whether the arc *a* in the graph *g* is a + *[bridge](../../../../index.md#bridge)* (aka *[cut + edge](../../../../index.md#cut_edge)*, or + *[isthmus](../../../../index.md#isthmus)*). The result is a boolean value, + __true__ if the arc is a bridge, and __false__ otherwise. + + The command will throw an error if *a* is not an arc of the graph *g*. + + - __struct::graph::op::isEulerian?__ *g* ?*tourvar*? + + This command determines whether the graph *g* is *eulerian* or not. The + result is a boolean value, __true__ if the graph is eulerian, and __false__ + otherwise. + + If the graph is eulerian and *tourvar* is specified then an euler tour is + computed as well and stored in the named variable. The tour is represented + by the list of arcs traversed, in the order of traversal. + + - __struct::graph::op::isSemiEulerian?__ *g* ?*pathvar*? + + This command determines whether the graph *g* is *semi-eulerian* or not. The + result is a boolean value, __true__ if the graph is semi-eulerian, and + __false__ otherwise. + + If the graph is semi-eulerian and *pathvar* is specified then an euler path + is computed as well and stored in the named variable. The path is + represented by the list of arcs traversed, in the order of traversal. + + - __struct::graph::op::dijkstra__ *g* *start* ?*options*...? + + This command determines distances in the weighted *g* from the node *start* + to all other nodes in the graph. The options specify how to traverse graphs, + and the format of the result. + + Two options are recognized + + * __-arcmode__ mode + + The accepted mode values are __directed__ and __undirected__. For + directed traversal all arcs are traversed from source to target. For + undirected traversal all arcs are traversed in the opposite direction as + well. Undirected traversal is the default. + + * __-outputformat__ format + + The accepted format values are __distances__ and __tree__. In both cases + the result is a dictionary keyed by the names of all nodes in the graph. + For __distances__ the value is the distance of the node to *start*, + whereas for __tree__ the value is the path from the node to *start*, + excluding the node itself, but including *start*. Tree format is the + default. + + - __struct::graph::op::distance__ *g* *origin* *destination* ?*options*...? + + This command determines the (un)directed distance between the two nodes + *origin* and *destination* in the graph *g*. It accepts the option + __-arcmode__ of __struct::graph::op::dijkstra__. + + - __struct::graph::op::eccentricity__ *g* *n* ?*options*...? + + This command determines the (un)directed + *[eccentricity](../../../../index.md#eccentricity)* of the node *n* in the + graph *g*. It accepts the option __-arcmode__ of + __struct::graph::op::dijkstra__. + + The (un)directed *[eccentricity](../../../../index.md#eccentricity)* of a + node is the maximal (un)directed distance between the node and any other + node in the graph. + + - __struct::graph::op::radius__ *g* ?*options*...? + + This command determines the (un)directed + *[radius](../../../../index.md#radius)* of the graph *g*. It accepts the + option __-arcmode__ of __struct::graph::op::dijkstra__. + + The (un)directed *[radius](../../../../index.md#radius)* of a graph is the + minimal (un)directed *[eccentricity](../../../../index.md#eccentricity)* of + all nodes in the graph. + + - __struct::graph::op::diameter__ *g* ?*options*...? + + This command determines the (un)directed + *[diameter](../../../../index.md#diameter)* of the graph *g*. It accepts the + option __-arcmode__ of __struct::graph::op::dijkstra__. + + The (un)directed *[diameter](../../../../index.md#diameter)* of a graph is + the maximal (un)directed *[eccentricity](../../../../index.md#eccentricity)* + of all nodes in the graph. + + - __struct::graph::op::BellmanFord__ *G* *startnode* + + Searching for [shortests paths](#subsection1) between chosen node and all + other nodes in graph *G*. Based on relaxation method. In comparison to + __struct::graph::op::dijkstra__ it doesn't need assumption that all weights + on edges in input graph *G* have to be positive. + + That generality sets the complexity of algorithm to - *O(V*E)*, where *V* is + the number of vertices and *[E](../../../../index.md#e)* is number of edges + in graph *G*. + + * Arguments: + + + Graph object *G* (input) + + Directed, connected and edge weighted graph *G*, without any + negative cycles ( presence of cycles with the negative sum of weight + means that there is no shortest path, since the total weight becomes + lower each time the cycle is traversed ). Negative weights on edges + are allowed. + + + Node *startnode* (input) + + The node for which we find all shortest paths to each other node in + graph *G*. + + * Result: + + Dictionary containing for each node (key) distances to each other node + in graph *G*. + + *Note:* If algorithm finds a negative cycle, it will return error message. + + - __struct::graph::op::Johnsons__ *G* ?*options*...? + + Searching for [shortest paths](#subsection1) between all pairs of vertices + in graph. For sparse graphs asymptotically quicker than + __struct::graph::op::FloydWarshall__ algorithm. Johnson's algorithm uses + __struct::graph::op::BellmanFord__ and __struct::graph::op::dijkstra__ as + subprocedures. + + Time complexity: *O(n**2*log(n) +n*m)*, where *n* is the number of nodes and + *m* is the number of edges in graph *G*. + + * Arguments: + + + Graph object *G* (input) + + Directed graph *G*, weighted on edges and not containing any cycles + with negative sum of weights ( the presence of such cycles means + there is no shortest path, since the total weight becomes lower each + time the cycle is traversed ). Negative weights on edges are + allowed. + + * Options: + + + __-filter__ + + Returns only existing distances, cuts all *Inf* values for + non-existing connections between pairs of nodes. + + * Result: + + Dictionary containing distances between all pairs of vertices. + + - __struct::graph::op::FloydWarshall__ *G* + + Searching for [shortest paths](#subsection1) between all pairs of edges in + weighted graphs. + + Time complexity: *O(V^3)* - where *V* is number of vertices. + + Memory complexity: *O(V^2)*. + + * Arguments: + + + Graph object *G* (input) + + Directed and weighted graph *G*. + + * Result: + + Dictionary containing shortest distances to each node from each node. + + *Note:* Algorithm finds solutions dynamically. It compares all possible + paths through the graph between each pair of vertices. Graph shouldn't + possess any cycle with negative sum of weights (the presence of such cycles + means there is no shortest path, since the total weight becomes lower each + time the cycle is traversed). + + On the other hand algorithm can be used to find those cycles - if any + shortest distance found by algorithm for any nodes *v* and *u* (when *v* is + the same node as *u*) is negative, that node surely belong to at least one + negative cycle. + + - __struct::graph::op::MetricTravellingSalesman__ *G* + + Algorithm for solving a metric variation of [Travelling salesman + problem](#subsection2). *TSP problem* is *NP-Complete*, so there is no + efficient algorithm to solve it. Greedy methods are getting extremely slow, + with the increase in the set of nodes. + + * Arguments: + + + Graph object *G* (input) + + Undirected, weighted graph *G*. + + * Result: + + Approximated solution of minimum *Hamilton Cycle* - closed path visiting + all nodes, each exactly one time. + + *Note:* [It's 2-approximation algorithm.](#subsection7) + + - __struct::graph::op::Christofides__ *G* + + Another algorithm for solving [metric *TSP problem*](#subsection2). + Christofides implementation uses *Max Matching* for reaching better + approximation factor. + + * Arguments: + + + Graph Object *G* (input) + + Undirected, weighted graph *G*. + + * Result: + + Approximated solution of minimum *Hamilton Cycle* - closed path visiting + all nodes, each exactly one time. + + *Note:* [It's is a 3/2 approximation algorithm. ](#subsection7) + + - __struct::graph::op::GreedyMaxMatching__ *G* + + *Greedy Max Matching* procedure, which finds [maximal + matching](#subsection3) (not maximum) for given graph *G*. It adds edges to + solution, beginning from edges with the lowest cost. + + * Arguments: + + + Graph Object *G* (input) + + Undirected graph *G*. + + * Result: + + Set of edges - the max matching for graph *G*. + + - __struct::graph::op::MaxCut__ *G* *U* *V* + + Algorithm solving a [Maximum Cut Problem](#subsection4). + + * Arguments: + + + Graph Object *G* (input) + + The graph to cut. + + + List *U* (output) + + Variable storing first set of nodes (cut) given by solution. + + + List *V* (output) + + Variable storing second set of nodes (cut) given by solution. + + * Result: + + Algorithm returns number of edges between found two sets of nodes. + + *Note:* *MaxCut* is a [2-approximation algorithm.](#subsection7) + + - __struct::graph::op::UnweightedKCenter__ *G* *k* + + Approximation algorithm that solves a [k-center problem](#subsection5). + + * Arguments: + + + Graph Object *G* (input) + + Undirected complete graph *G*, which satisfies triangle inequality. + + + Integer *k* (input) + + Positive integer that sets the number of nodes that will be included + in *k-center*. + + * Result: + + Set of nodes - *k* center for graph *G*. + + *Note:* *UnweightedKCenter* is a [2-approximation algorithm.](#subsection7) + + - __struct::graph::op::WeightedKCenter__ *G* *nodeWeights* *W* + + Approximation algorithm that solves a weighted version of [k-center + problem](#subsection5). + + * Arguments: + + + Graph Object *G* (input) + + Undirected complete graph *G*, which satisfies triangle inequality. + + + Integer *W* (input) + + Positive integer that sets the maximum possible weight of *k-center* + found by algorithm. + + + List *nodeWeights* (input) + + List of nodes and its weights in graph *G*. + + * Result: + + Set of nodes, which is solution found by algorithm. + + *Note:**WeightedKCenter* is a [3-approximation algorithm.](#subsection7) + + - __struct::graph::op::GreedyMaxIndependentSet__ *G* + + A *maximal independent set* is an *[independent + set](../../../../index.md#independent_set)* such that adding any other node + to the set forces the set to contain an edge. + + Algorithm for input graph *G* returns set of nodes (list), which are + contained in Max Independent Set found by algorithm. + + - __struct::graph::op::GreedyWeightedMaxIndependentSet__ *G* *nodeWeights* + + Weighted variation of *Maximal Independent Set*. It takes as an input + argument not only graph *G* but also set of weights for all vertices in + graph *G*. + + *Note:* Read also *Maximal Independent Set* description for more info. + + - __struct::graph::op::VerticesCover__ *G* + + *Vertices cover* is a set of vertices such that each edge of the graph is + incident to at least one vertex of the set. This 2-approximation algorithm + searches for minimum *vertices cover*, which is a classical optimization + problem in computer science and is a typical example of an *NP-hard* + optimization problem that has an approximation algorithm. For input graph + *G* algorithm returns the set of edges (list), which is Vertex Cover found + by algorithm. + + - __struct::graph::op::EdmondsKarp__ *G* *s* *t* + + Improved Ford-Fulkerson's algorithm, computing the [maximum + flow](#subsection6) in given flow network *G*. + + * Arguments: + + + Graph Object *G* (input) + + Weighted and directed graph. Each edge should have set integer + attribute considered as maximum throughputs that can be carried by + that link (edge). + + + Node *s* (input) + + The node that is a source for graph *G*. + + + Node *t* (input) + + The node that is a sink for graph *G*. + + * Result: + + Procedure returns the dictionary containing throughputs for all edges. + For each key ( the edge between nodes *u* and *v* in the form of *list u + v* ) there is a value that is a throughput for that key. Edges where + throughput values are equal to 0 are not returned ( it is like there was + no link in the flow network between nodes connected by such edge). + + The general idea of algorithm is finding the shortest augumenting paths in + graph *G*, as long as they exist, and for each path updating the edge's + weights along that path, with maximum possible throughput. The final + (maximum) flow is found when there is no other augumenting path from source + to sink. + + *Note:* Algorithm complexity : *O(V*E)*, where *V* is the number of nodes + and *[E](../../../../index.md#e)* is the number of edges in graph *G*. + + - __struct::graph::op::BusackerGowen__ *G* *desiredFlow* *s* *t* + + Algorithm finds solution for a [minimum cost flow problem](#subsection6). + So, the goal is to find a flow, whose max value can be *desiredFlow*, from + source node *s* to sink node *t* in given flow network *G*. That network + except throughputs at edges has also defined a non-negative cost on each + edge - cost of using that edge when directing flow with that edge ( it can + illustrate e.g. fuel usage, time or any other measure dependent on usages ). + + * Arguments: + + + Graph Object *G* (input) + + Flow network (directed graph), each edge in graph should have two + integer attributes: *cost* and *throughput*. + + + Integer *desiredFlow* (input) + + Max value of the flow for that network. + + + Node *s* (input) + + The source node for graph *G*. + + + Node *t* (input) + + The sink node for graph *G*. + + * Result: + + Dictionary containing values of used throughputs for each edge ( key ). + found by algorithm. + + *Note:* Algorithm complexity : *O(V**2*desiredFlow)*, where *V* is the + number of nodes in graph *G*. + + - __struct::graph::op::ShortestsPathsByBFS__ *G* *s* *outputFormat* + + Shortest pathfinding algorithm using BFS method. In comparison to + __struct::graph::op::dijkstra__ it can work with negative weights on edges. + Of course negative cycles are not allowed. Algorithm is better than dijkstra + for sparse graphs, but also there exist some pathological cases (those cases + generally don't appear in practise) that make time complexity increase + exponentially with the growth of the number of nodes. + + * Arguments: + + + Graph Object *G* (input) + + Input graph. + + + Node *s* (input) + + Source node for which all distances to each other node in graph *G* + are computed. + + * Options and result: + + + __distances__ + + When selected *outputFormat* is __distances__ - procedure returns + dictionary containing distances between source node *s* and each + other node in graph *G*. + + + __paths__ + + When selected *outputFormat* is __paths__ - procedure returns + dictionary containing for each node *v*, a list of nodes, which is a + path between source node *s* and node *v*. + + - __struct::graph::op::BFS__ *G* *s* ?*outputFormat*...? + + Breadth-First Search - algorithm creates the BFS Tree. Memory and time + complexity: *O(V + E)*, where *V* is the number of nodes and + *[E](../../../../index.md#e)* is number of edges. + + * Arguments: + + + Graph Object *G* (input) + + Input graph. + + + Node *s* (input) + + Source node for BFS procedure. + + * Options and result: + + + __graph__ + + When selected __outputFormat__ is __graph__ - procedure returns a + graph structure (__[struct::graph](graph.md)__), which is equivalent + to BFS tree found by algorithm. + + + __tree__ + + When selected __outputFormat__ is __tree__ - procedure returns a + tree structure (__[struct::tree](struct_tree.md)__), which is + equivalent to BFS tree found by algorithm. + + - __struct::graph::op::MinimumDiameterSpanningTree__ *G* + + The goal is to find for input graph *G*, the *spanning tree* that has the + minimum *[diameter](../../../../index.md#diameter)* value. + + General idea of algorithm is to run *[BFS](../../../../index.md#bfs)* over + all vertices in graph *G*. If the diameter *d* of the tree is odd, then we + are sure that tree given by *[BFS](../../../../index.md#bfs)* is minimum + (considering diameter value). When, diameter *d* is even, then optimal tree + can have minimum *[diameter](../../../../index.md#diameter)* equal to *d* or + *d-1*. + + In that case, what algorithm does is rebuilding the tree given by + *[BFS](../../../../index.md#bfs)*, by adding a vertice between root node and + root's child node (nodes), such that subtree created with child node as root + node is the greatest one (has the greatests height). In the next step for + such rebuilded tree, we run again *[BFS](../../../../index.md#bfs)* with new + node as root node. If the height of the tree didn't changed, we have found a + better solution. + + For input graph *G* algorithm returns the graph structure + (__[struct::graph](graph.md)__) that is a spanning tree with minimum + diameter found by algorithm. + + - __struct::graph::op::MinimumDegreeSpanningTree__ *G* + + Algorithm finds for input graph *G*, a spanning tree *T* with the minimum + possible degree. That problem is *NP-hard*, so algorithm is an approximation + algorithm. + + Let *V* be the set of nodes for graph *G* and let *W* be any subset of *V*. + Lets assume also that *OPT* is optimal solution and *ALG* is solution found + by algorithm for input graph *G*. + + It can be proven that solution found with the algorithm must fulfil + inequality: + + *((|W| + k - 1) / |W|) <= ALG <= 2*OPT + log2(n) + 1*. + + * Arguments: + + + Graph Object *G* (input) + + Undirected simple graph. + + * Result: + + Algorithm returns graph structure, which is equivalent to spanning tree + *T* found by algorithm. + + - __struct::graph::op::MaximumFlowByDinic__ *G* *s* *t* *blockingFlowAlg* + + Algorithm finds [maximum flow](#subsection6) for the flow network + represented by graph *G*. It is based on the blocking-flow finding methods, + which give us different complexities what makes a better fit for different + graphs. + + * Arguments: + + + Graph Object *G* (input) + + Directed graph *G* representing the flow network. Each edge should + have attribute *throughput* set with integer value. + + + Node *s* (input) + + The source node for the flow network *G*. + + + Node *t* (input) + + The sink node for the flow network *G*. + + * Options: + + + __dinic__ + + Procedure will find maximum flow for flow network *G* using Dinic's + algorithm (__struct::graph::op::BlockingFlowByDinic__) for blocking + flow computation. + + + __mkm__ + + Procedure will find maximum flow for flow network *G* using + Malhotra, Kumar and Maheshwari's algorithm + (__struct::graph::op::BlockingFlowByMKM__) for blocking flow + computation. + + * Result: + + Algorithm returns dictionary containing it's flow value for each edge + (key) in network *G*. + + *Note:* __struct::graph::op::BlockingFlowByDinic__ gives *O(m*n^2)* + complexity and __struct::graph::op::BlockingFlowByMKM__ gives *O(n^3)* + complexity, where *n* is the number of nodes and *m* is the number of edges + in flow network *G*. + + - __struct::graph::op::BlockingFlowByDinic__ *G* *s* *t* + + Algorithm for given network *G* with source *s* and sink *t*, finds a + [blocking flow](#subsection6), which can be used to obtain a *[maximum + flow](../../../../index.md#maximum_flow)* for that network *G*. + + * Arguments: + + + Graph Object *G* (input) + + Directed graph *G* representing the flow network. Each edge should + have attribute *throughput* set with integer value. + + + Node *s* (input) + + The source node for the flow network *G*. + + + Node *t* (input) + + The sink node for the flow network *G*. + + * Result: + + Algorithm returns dictionary containing it's blocking flow value for + each edge (key) in network *G*. + + *Note:* Algorithm's complexity is *O(n*m)*, where *n* is the number of nodes + and *m* is the number of edges in flow network *G*. + + - __struct::graph::op::BlockingFlowByMKM__ *G* *s* *t* + + Algorithm for given network *G* with source *s* and sink *t*, finds a + [blocking flow](#subsection6), which can be used to obtain a *[maximum + flow](../../../../index.md#maximum_flow)* for that + *[network](../../../../index.md#network)* *G*. + + * Arguments: + + + Graph Object *G* (input) + + Directed graph *G* representing the flow network. Each edge should + have attribute *throughput* set with integer value. + + + Node *s* (input) + + The source node for the flow network *G*. + + + Node *t* (input) + + The sink node for the flow network *G*. + + * Result: + + Algorithm returns dictionary containing it's blocking flow value for + each edge (key) in network *G*. + + *Note:* Algorithm's complexity is *O(n^2)*, where *n* is the number of nodes + in flow network *G*. + + - __struct::graph::op::createResidualGraph__ *G* *f* + + Procedure creates a *[residual graph](../../../../index.md#residual_graph)* + (or [residual network](#subsection6) ) for network *G* and given flow *f*. + + * Arguments: + + + Graph Object *G* (input) + + Flow network (directed graph where each edge has set attribute: + *throughput* ). + + + dictionary *f* (input) + + Current flows in flow network *G*. + + * Result: + + Procedure returns graph structure that is a *[residual + graph](../../../../index.md#residual_graph)* created from input flow + network *G*. + + - __struct::graph::op::createAugmentingNetwork__ *G* *f* *path* + + Procedure creates an [augmenting network](#subsection6) for a given residual + network *G* , flow *f* and augmenting path *path*. + + * Arguments: + + + Graph Object *G* (input) + + Residual network (directed graph), where for every edge there are + set two attributes: throughput and cost. + + + Dictionary *f* (input) + + Dictionary which contains for every edge (key), current value of the + flow on that edge. + + + List *path* (input) + + Augmenting path, set of edges (list) for which we create the network + modification. + + * Result: + + Algorithm returns graph structure containing the modified augmenting + network. + + - __struct::graph::op::createLevelGraph__ *Gf* *s* + + For given residual graph *Gf* procedure finds the [level + graph](#subsection6). + + * Arguments: + + + Graph Object *Gf* (input) + + Residual network, where each edge has it's attribute *throughput* + set with certain value. + + + Node *s* (input) + + The source node for the residual network *Gf*. + + * Result: + + Procedure returns a *[level graph](../../../../index.md#level_graph)* + created from input *residual network*. + + - __struct::graph::op::TSPLocalSearching__ *G* *C* + + Algorithm is a *heuristic of local searching* for *Travelling Salesman + Problem*. For some solution of *TSP problem*, it checks if it's possible to + find a better solution. As *TSP* is well known NP-Complete problem, so + algorithm is a approximation algorithm (with 2 approximation factor). + + * Arguments: + + + Graph Object *G* (input) + + Undirected and complete graph with attributes "weight" set on each + single edge. + + + List *C* (input) + + A list of edges being *Hamiltonian cycle*, which is solution of *TSP + Problem* for graph *G*. + + * Result: + + Algorithm returns the best solution for *TSP problem*, it was able to + find. + + *Note:* The solution depends on the choosing of the beginning cycle *C*. + It's not true that better cycle assures that better solution will be found, + but practise shows that we should give starting cycle with as small sum of + weights as possible. + + - __struct::graph::op::TSPLocalSearching3Approx__ *G* *C* + + Algorithm is a *heuristic of local searching* for *Travelling Salesman + Problem*. For some solution of *TSP problem*, it checks if it's possible to + find a better solution. As *TSP* is well known NP-Complete problem, so + algorithm is a approximation algorithm (with 3 approximation factor). + + * Arguments: + + + Graph Object *G* (input) + + Undirected and complete graph with attributes "weight" set on each + single edge. + + + List *C* (input) + + A list of edges being *Hamiltonian cycle*, which is solution of *TSP + Problem* for graph *G*. + + * Result: + + Algorithm returns the best solution for *TSP problem*, it was able to + find. + + *Note:* In practise 3-approximation algorithm turns out to be far more + effective than 2-approximation, but it gives worser approximation factor. + Further heuristics of local searching (e.g. 4-approximation) doesn't give + enough boost to square the increase of approximation factor, so 2 and 3 + approximations are mainly used. + + - __struct::graph::op::createSquaredGraph__ *G* + + X-Squared graph is a graph with the same set of nodes as input graph *G*, + but a different set of edges. X-Squared graph has edge *(u,v)*, if and only + if, the distance between *u* and *v* nodes is not greater than X and *u != + v*. + + Procedure for input graph *G*, returns its two-squared graph. + + *Note:* Distances used in choosing new set of edges are considering the + number of edges, not the sum of weights at edges. + + - __struct::graph::op::createCompleteGraph__ *G* *originalEdges* + + For input graph *G* procedure adds missing arcs to make it a *[complete + graph](../../../../index.md#complete_graph)*. It also holds in variable + *originalEdges* the set of arcs that graph *G* possessed before that + operation. + +# Background theory and terms + +## Shortest Path Problem + + - Definition (*single-pair shortest path problem*): + + Formally, given a weighted graph (let *V* be the set of vertices, and + *[E](../../../../index.md#e)* a set of edges), and one vertice *v* of *V*, + find a path *P* from *v* to a *v'* of V so that the sum of weights on edges + along the path is minimal among all paths connecting v to v'. + + - Generalizations: + + *The single-source shortest path problem*, in which we have to find shortest + paths from a source vertex v to all other vertices in the graph. + + *The single-destination shortest path problem*, in which we have to find + shortest paths from all vertices in the graph to a single destination vertex + v. This can be reduced to the single-source shortest path problem by + reversing the edges in the graph. + + *The all-pairs shortest path problem*, in which we have to find shortest + paths between every pair of vertices v, v' in the graph. + + *Note:* The result of *Shortest Path problem* can be *Shortest Path tree*, + which is a subgraph of a given (possibly weighted) graph constructed so that + the distance between a selected root node and all other nodes is minimal. It + is a tree because if there are two paths between the root node and some + vertex v (i.e. a cycle), we can delete the last edge of the longer path + without increasing the distance from the root node to any node in the + subgraph. + +## Travelling Salesman Problem + + - Definition: + + For given edge-weighted (weights on edges should be positive) graph the goal + is to find the cycle that visits each node in graph exactly once + (*Hamiltonian cycle*). + + - Generalizations: + + *Metric TSP* - A very natural restriction of the *TSP* is to require that + the distances between cities form a *metric*, i.e., they satisfy *the + triangle inequality*. That is, for any 3 cities *A*, *B* and + *[C](../../../../index.md#c)*, the distance between *A* and + *[C](../../../../index.md#c)* must be at most the distance from *A* to *B* + plus the distance from *B* to *[C](../../../../index.md#c)*. Most natural + instances of *TSP* satisfy this constraint. + + *Euclidean TSP* - Euclidean TSP, or *planar TSP*, is the *TSP* with the + distance being the ordinary *Euclidean distance*. *Euclidean TSP* is a + particular case of *TSP* with *triangle inequality*, since distances in + plane obey triangle inequality. However, it seems to be easier than general + *TSP* with *triangle inequality*. For example, *the minimum spanning tree* + of the graph associated with an instance of *Euclidean TSP* is a *Euclidean + minimum spanning tree*, and so can be computed in expected *O(n log n)* time + for *n* points (considerably less than the number of edges). This enables + the simple *2-approximation algorithm* for TSP with triangle inequality + above to operate more quickly. + + *Asymmetric TSP* - In most cases, the distance between two nodes in the + *TSP* network is the same in both directions. The case where the distance + from *A* to *B* is not equal to the distance from *B* to *A* is called + *asymmetric TSP*. A practical application of an *asymmetric TSP* is route + optimisation using street-level routing (asymmetric due to one-way streets, + slip-roads and motorways). + +## Matching Problem + + - Definition: + + Given a graph *G = (V,E)*, a matching or *edge-independent set* *M* in *G* + is a set of pairwise non-adjacent edges, that is, no two edges share a + common vertex. A vertex is *matched* if it is incident to an edge in the + *matching M*. Otherwise the vertex is *unmatched*. + + - Generalizations: + + *Maximal matching* - a matching *M* of a graph G with the property that if + any edge not in *M* is added to *M*, it is no longer a + *[matching](../../../../index.md#matching)*, that is, *M* is maximal if it + is not a proper subset of any other + *[matching](../../../../index.md#matching)* in graph G. In other words, a + *matching M* of a graph G is maximal if every edge in G has a non-empty + intersection with at least one edge in *M*. + + *Maximum matching* - a matching that contains the largest possible number of + edges. There may be many *maximum matchings*. The *matching number* of a + graph G is the size of a *maximum matching*. Note that every *maximum + matching* is *maximal*, but not every *maximal matching* is a *maximum + matching*. + + *Perfect matching* - a matching which matches all vertices of the graph. + That is, every vertex of the graph is incident to exactly one edge of the + matching. Every *perfect matching* is + *[maximum](../../../../index.md#maximum)* and hence *maximal*. In some + literature, the term *complete matching* is used. A *perfect matching* is + also a *minimum-size edge cover*. Moreover, the size of a *maximum matching* + is no larger than the size of a *minimum edge cover*. + + *Near-perfect matching* - a matching in which exactly one vertex is + unmatched. This can only occur when the graph has an odd number of vertices, + and such a *[matching](../../../../index.md#matching)* must be + *[maximum](../../../../index.md#maximum)*. If, for every vertex in a graph, + there is a near-perfect matching that omits only that vertex, the graph is + also called *factor-critical*. + + - Related terms: + + *Alternating path* - given a matching *M*, an *alternating path* is a path + in which the edges belong alternatively to the matching and not to the + matching. + + *[Augmenting path](../../../../index.md#augmenting_path)* - given a matching + *M*, an *[augmenting path](../../../../index.md#augmenting_path)* is an + *alternating path* that starts from and ends on free (unmatched) vertices. + +## Cut Problems + + - Definition: + + A *cut* is a partition of the vertices of a graph into two *disjoint + subsets*. The *cut-set* of the *cut* is the set of edges whose end points + are in different subsets of the partition. Edges are said to be crossing the + cut if they are in its *cut-set*. + + Formally: + + a *cut* *C = (S,T)* is a partition of *V* of a graph *G = (V, E)*. + + an *s-t cut* *C = (S,T)* of a *[flow + network](../../../../index.md#flow_network)* *N = (V, E)* is a cut of *N* + such that *s* is included in *S* and *t* is included in *T*, where *s* and + *t* are the *[source](../../../../index.md#source)* and the *sink* of *N* + respectively. + + The *cut-set* of a *cut C = (S,T)* is such set of edges from graph *G = (V, + E)* that each edge *(u, v)* satisfies condition that *u* is included in *S* + and *v* is included in *T*. + + In an *unweighted undirected* graph, the size or weight of a cut is the + number of edges crossing the cut. In a *weighted graph*, the same term is + defined by the sum of the weights of the edges crossing the cut. + + In a *[flow network](../../../../index.md#flow_network)*, an *s-t cut* is a + cut that requires the *[source](../../../../index.md#source)* and the *sink* + to be in different subsets, and its *cut-set* only consists of edges going + from the *source's* side to the *sink's* side. The capacity of an *s-t cut* + is defined by the sum of capacity of each edge in the *cut-set*. + + The *cut* of a graph can sometimes refer to its *cut-set* instead of the + partition. + + - Generalizations: + + *Minimum cut* - A cut is minimum if the size of the cut is not larger than + the size of any other cut. + + *Maximum cut* - A cut is maximum if the size of the cut is not smaller than + the size of any other cut. + + *Sparsest cut* - The *Sparsest cut problem* is to bipartition the vertices + so as to minimize the ratio of the number of edges across the cut divided by + the number of vertices in the smaller half of the partition. + +## K-Center Problem + + - Definitions: + + * *Unweighted K-Center* + + For any set *S* ( which is subset of *V* ) and node *v*, let the + *connect(v,S)* be the cost of cheapest edge connecting *v* with any node + in *S*. The goal is to find such *S*, that *|S| = k* and + *max_v{connect(v,S)}* is possibly small. + + In other words, we can use it i.e. for finding best locations in the + city ( nodes of input graph ) for placing k buildings, such that those + buildings will be as close as possible to all other locations in town. + + * *Weighted K-Center* + + The variation of *unweighted k-center problem*. Besides the fact graph + is edge-weighted, there are also weights on vertices of input graph *G*. + We've got also restriction *W*. The goal is to choose such set of nodes + *S* ( which is a subset of *V* ), that it's total weight is not greater + than *W* and also function: *max_v { min_u { cost(u,v) }}* has the + smallest possible worth ( *v* is a node in *V* and *u* is a node in *S* + ). + +## Flow Problems + + - Definitions: + + *the maximum flow problem* - the goal is to find a feasible flow through a + single-source, single-sink flow network that is maximum. The *maximum flow + problem* can be seen as a special case of more complex network flow + problems, such as the *circulation problem*. The maximum value of an *s-t + flow* is equal to the minimum capacity of an *s-t cut* in the network, as + stated in the *max-flow min-cut theorem*. + + More formally for flow network *G = (V,E)*, where for each edge *(u, v)* we + have its throuhgput *c(u,v)* defined. As *[flow](../../../../index.md#flow)* + *F* we define set of non-negative integer attributes *f(u,v)* assigned to + edges, satisfying such conditions: + + for each edge *(u, v)* in *G* such condition should be satisfied: 0 <= + f(u,v) <= c(u,v) + + Network *G* has source node *s* such that the flow *F* is equal to the sum + of outcoming flow decreased by the sum of incoming flow from that source + node *s*. + + Network *G* has sink node *t* such that the the *-F* value is equal to the + sum of the incoming flow decreased by the sum of outcoming flow from that + sink node *t*. + + For each node that is not a *[source](../../../../index.md#source)* or + *sink* the sum of incoming flow and sum of outcoming flow should be equal. + + *the minimum cost flow problem* - the goal is finding the cheapest possible + way of sending a certain amount of flow through a *[flow + network](../../../../index.md#flow_network)*. + + *[blocking flow](../../../../index.md#blocking_flow)* - a *[blocking + flow](../../../../index.md#blocking_flow)* for a *residual network* *Gf* we + name such flow *b* in *Gf* that: + + Each path from *sink* to *[source](../../../../index.md#source)* is the + shortest path in *Gf*. + + Each shortest path in *Gf* contains an edge with fully used throughput in + *Gf+b*. + + *residual network* - for a flow network *G* and flow *f* *residual network* + is built with those edges, which can send larger flow. It contains only + those edges, which can send flow larger than 0. + + *level network* - it has the same set of nodes as *[residual + graph](../../../../index.md#residual_graph)*, but has only those edges + *(u,v)* from *Gf* for which such equality is satisfied: *distance(s,u)+1 = + distance(s,v)*. + + *[augmenting network](../../../../index.md#augmenting_network)* - it is a + modification of *residual network* considering the new flow values. + Structure stays unchanged but values of throughputs and costs at edges are + different. + +## Approximation algorithm + + - k-approximation algorithm: + + Algorithm is a k-approximation, when for *ALG* (solution returned by + algorithm) and *OPT* (optimal solution), such inequality is true: + + for minimalization problems: *ALG/OPT <= k* + + for maximalization problems: *OPT/ALG <= k* + +# References + + 1. [Adjacency matrix](http://en.wikipedia.org/wiki/Adjacency_matrix) + + 1. [Adjacency list](http://en.wikipedia.org/wiki/Adjacency_list) + + 1. [Kruskal's algorithm](http://en.wikipedia.org/wiki/Kruskal%27s_algorithm) + + 1. [Prim's algorithm](http://en.wikipedia.org/wiki/Prim%27s_algorithm) + + 1. [Bipartite graph](http://en.wikipedia.org/wiki/Bipartite_graph) + + 1. [Strongly connected + components](http://en.wikipedia.org/wiki/Strongly_connected_components) + + 1. [Tarjan's strongly connected components + algorithm](http://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm) + + 1. [Cut vertex](http://en.wikipedia.org/wiki/Cut_vertex) + + 1. [Bridge](http://en.wikipedia.org/wiki/Bridge_(graph_theory)) + + 1. [Bellman-Ford's + algorithm](http://en.wikipedia.org/wiki/Bellman-Ford_algorithm) + + 1. [Johnson's algorithm](http://en.wikipedia.org/wiki/Johnson_algorithm) + + 1. [Floyd-Warshall's + algorithm](http://en.wikipedia.org/wiki/Floyd-Warshall_algorithm) + + 1. [Travelling Salesman + Problem](http://en.wikipedia.org/wiki/Travelling_salesman_problem) + + 1. [Christofides + Algorithm](http://en.wikipedia.org/wiki/Christofides_algorithm) + + 1. [Max Cut](http://en.wikipedia.org/wiki/Maxcut) + + 1. [Matching](http://en.wikipedia.org/wiki/Matching) + + 1. [Max Independent Set](http://en.wikipedia.org/wiki/Maximal_independent_set) + + 1. [Vertex Cover](http://en.wikipedia.org/wiki/Vertex_cover_problem) + + 1. [Ford-Fulkerson's + algorithm](http://en.wikipedia.org/wiki/Ford-Fulkerson_algorithm) + + 1. [Maximum Flow problem](http://en.wikipedia.org/wiki/Maximum_flow_problem) + + 1. [Busacker-Gowen's + algorithm](http://en.wikipedia.org/wiki/Minimum_cost_flow_problem) + + 1. [Dinic's algorithm](http://en.wikipedia.org/wiki/Dinic's_algorithm) + + 1. [K-Center problem](http://www.csc.kth.se/~viggo/wwwcompendium/node128.html) + + 1. [BFS](http://en.wikipedia.org/wiki/Breadth-first_search) + + 1. [Minimum Degree Spanning + Tree](http://en.wikipedia.org/wiki/Degree-constrained_spanning_tree) + + 1. [Approximation + algorithm](http://en.wikipedia.org/wiki/Approximation_algorithm) + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: graph* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[adjacency list](../../../../index.md#adjacency_list), [adjacency +matrix](../../../../index.md#adjacency_matrix), +[adjacent](../../../../index.md#adjacent), [approximation +algorithm](../../../../index.md#approximation_algorithm), +[arc](../../../../index.md#arc), [articulation +point](../../../../index.md#articulation_point), [augmenting +network](../../../../index.md#augmenting_network), [augmenting +path](../../../../index.md#augmenting_path), [bfs](../../../../index.md#bfs), +[bipartite](../../../../index.md#bipartite), [blocking +flow](../../../../index.md#blocking_flow), +[bridge](../../../../index.md#bridge), [complete +graph](../../../../index.md#complete_graph), [connected +component](../../../../index.md#connected_component), [cut +edge](../../../../index.md#cut_edge), [cut +vertex](../../../../index.md#cut_vertex), [degree](../../../../index.md#degree), +[degree constrained spanning +tree](../../../../index.md#degree_constrained_spanning_tree), +[diameter](../../../../index.md#diameter), +[dijkstra](../../../../index.md#dijkstra), +[distance](../../../../index.md#distance), +[eccentricity](../../../../index.md#eccentricity), +[edge](../../../../index.md#edge), [flow +network](../../../../index.md#flow_network), +[graph](../../../../index.md#graph), +[heuristic](../../../../index.md#heuristic), [independent +set](../../../../index.md#independent_set), +[isthmus](../../../../index.md#isthmus), [level +graph](../../../../index.md#level_graph), [local +searching](../../../../index.md#local_searching), +[loop](../../../../index.md#loop), [matching](../../../../index.md#matching), +[max cut](../../../../index.md#max_cut), [maximum +flow](../../../../index.md#maximum_flow), [minimal spanning +tree](../../../../index.md#minimal_spanning_tree), [minimum cost +flow](../../../../index.md#minimum_cost_flow), [minimum degree spanning +tree](../../../../index.md#minimum_degree_spanning_tree), [minimum diameter +spanning tree](../../../../index.md#minimum_diameter_spanning_tree), +[neighbour](../../../../index.md#neighbour), [node](../../../../index.md#node), +[radius](../../../../index.md#radius), [residual +graph](../../../../index.md#residual_graph), [shortest +path](../../../../index.md#shortest_path), [squared +graph](../../../../index.md#squared_graph), [strongly connected +component](../../../../index.md#strongly_connected_component), +[subgraph](../../../../index.md#subgraph), [travelling +salesman](../../../../index.md#travelling_salesman), +[vertex](../../../../index.md#vertex), [vertex +cover](../../../../index.md#vertex_cover) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2008 Alejandro Paz +Copyright © 2008 (docs) Andreas Kupries +Copyright © 2009 Michal Antoniewski ADDED embedded/md/tcllib/files/modules/struct/matrix.md Index: embedded/md/tcllib/files/modules/struct/matrix.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/matrix.md @@ -0,0 +1,524 @@ + +[//000000001]: # (struct::matrix - Tcl Data Structures) +[//000000002]: # (Generated from file 'matrix.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::matrix(n) 2.0.3 tcllib "Tcl Data Structures") + +# NAME + +struct::matrix - Create and manipulate matrix objects + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [EXAMPLES](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require struct::matrix ?2.0.3? + +[__::struct::matrix__ ?*matrixName*? ?__=__|__:=__|__as__|__deserialize__ *source*?](#1) +[__matrixName__ *option* ?*arg arg ...*?](#2) +[*matrixName* __=__ *sourcematrix*](#3) +[*matrixName* __-->__ *destmatrix*](#4) +[*matrixName* __add column__ ?*values*?](#5) +[*matrixName* __add row__ ?*values*?](#6) +[*matrixName* __add columns__ *n*](#7) +[*matrixName* __add rows__ *n*](#8) +[*matrixName* __cells__](#9) +[*matrixName* __cellsize__ *column row*](#10) +[*matrixName* __columns__](#11) +[*matrixName* __columnwidth__ *column*](#12) +[*matrixName* __delete column__ *column*](#13) +[*matrixName* __delete columns__ *n*](#14) +[*matrixName* __delete row__ *row*](#15) +[*matrixName* __delete rows__ *n*](#16) +[*matrixName* __deserialize__ *serialization*](#17) +[*matrixName* __destroy__](#18) +[*matrixName* __format 2string__ ?*report*?](#19) +[*matrixName* __format 2chan__ ??*report*? *channel*?](#20) +[*matrixName* __get cell__ *column row*](#21) +[*matrixName* __get column__ *column*](#22) +[*matrixName* __get rect__ *column_tl row_tl column_br row_br*](#23) +[*matrixName* __get row__ *row*](#24) +[*matrixName* __insert column__ *column* ?*values*?](#25) +[*matrixName* __insert row__ *row* ?*values*?](#26) +[*matrixName* __link__ ?-transpose? *arrayvar*](#27) +[*matrixName* __links__](#28) +[*matrixName* __rowheight__ *row*](#29) +[*matrixName* __rows__](#30) +[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __all__ *pattern*](#31) +[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __column__ *column pattern*](#32) +[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __row__ *row pattern*](#33) +[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __rect__ *column_tl row_tl column_br row_br pattern*](#34) +[*matrixName* __serialize__ ?*column_tl row_tl column_br row_br*?](#35) +[*matrixName* __set cell__ *column row value*](#36) +[*matrixName* __set column__ *column values*](#37) +[*matrixName* __set rect__ *column row values*](#38) +[*matrixName* __set row__ *row values*](#39) +[*matrixName* __sort columns__ ?__-increasing__|__-decreasing__? *row*](#40) +[*matrixName* __sort rows__ ?__-increasing__|__-decreasing__? *column*](#41) +[*matrixName* __swap columns__ *column_a column_b*](#42) +[*matrixName* __swap rows__ *row_a row_b*](#43) +[*matrixName* __transpose__](#44) +[*matrixName* __unlink__ *arrayvar*](#45) + +# DESCRIPTION + +A matrix is a rectangular collection of cells, i.e. organized in rows and +columns. Each cell contains exactly one value of arbitrary form. The cells in +the matrix are addressed by pairs of integer numbers, with the first (left) +number in the pair specifying the column and the second (right) number +specifying the row the cell is in. These indices are counted from 0 upward. The +special non-numeric index __end__ refers to the last row or column in the +matrix, depending on the context. Indices of the form __end__-__number__ are +counted from the end of the row or column, like they are for standard Tcl lists. +Trying to access non-existing cells causes an error. + +The matrices here are created empty, i.e. they have neither rows nor columns. +The user then has to add rows and columns as needed by his application. A +specialty of this structure is the ability to export an array-view onto its +contents. Such can be used by tkTable, for example, to link the matrix into the +display. + +The main command of the package is: + + - __::struct::matrix__ ?*matrixName*? ?__=__|__:=__|__as__|__deserialize__ *source*? + + The command creates a new matrix object with an associated global Tcl + command whose name is *matrixName*. This command may be used to invoke + various operations on the matrix. It has the following general form: + + * __matrixName__ *option* ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. + + If *matrixName* is not specified a unique name will be generated by the + package itself. If a *source* is specified the new matrix will be + initialized to it. For the operators __=__, __:=__, and __as__ the argument + *source* is interpreted as the name of another matrix object, and the + assignment operator __=__ will be executed. For __deserialize__ the *source* + is a serialized matrix object and __deserialize__ will be executed. + + In other words + + ::struct::matrix mymatrix = b + + is equivalent to + + ::struct::matrix mymatrix + mymatrix = b + + and + + ::struct::matrix mymatrix deserialize $b + + is equivalent to + + ::struct::matrix mymatrix + mymatrix deserialize $b + +The following commands are possible for matrix objects: + + - *matrixName* __=__ *sourcematrix* + + This is the assignment operator for matrix objects. It copies the matrix + contained in the matrix object *sourcematrix* over the matrix data in + *matrixName*. The old contents of *matrixName* are deleted by this + operation. + + This operation is in effect equivalent to + + *matrixName* __deserialize__ [*sourcematrix* __serialize__] + + - *matrixName* __-->__ *destmatrix* + + This is the reverse assignment operator for matrix objects. It copies the + matrix contained in the matrix object *matrixName* over the matrix data in + the object *destmatrix*. The old contents of *destmatrix* are deleted by + this operation. + + This operation is in effect equivalent to + + *destmatrix* __deserialize__ [*matrixName* __serialize__] + + - *matrixName* __add column__ ?*values*? + + Extends the matrix by one column and then acts like __set column__ (see + below) on this new column if there were *values* supplied. Without *values* + the new cells will be set to the empty string. The new column is appended + immediately behind the last existing column. + + - *matrixName* __add row__ ?*values*? + + Extends the matrix by one row and then acts like __set row__ (see below) on + this new row if there were *values* supplied. Without *values* the new cells + will be set to the empty string. The new row is appended immediately behind + the last existing row. + + - *matrixName* __add columns__ *n* + + Extends the matrix by *n* columns. The new cells will be set to the empty + string. The new columns are appended immediately behind the last existing + column. A value of *n* equal to or smaller than 0 is not allowed. + + - *matrixName* __add rows__ *n* + + Extends the matrix by *n* rows. The new cells will be set to the empty + string. The new rows are appended immediately behind the last existing row. + A value of *n* equal to or smaller than 0 is not allowed. + + - *matrixName* __cells__ + + Returns the number of cells currently managed by the matrix. This is the + product of __rows__ and __columns__. + + - *matrixName* __cellsize__ *column row* + + Returns the length of the string representation of the value currently + contained in the addressed cell. + + - *matrixName* __columns__ + + Returns the number of columns currently managed by the matrix. + + - *matrixName* __columnwidth__ *column* + + Returns the length of the longest string representation of all the values + currently contained in the cells of the addressed column if these are all + spanning only one line. For cell values spanning multiple lines the length + of their longest line goes into the computation. + + *Note:* The command recognizes ANSI color control sequences and excludes + them from the width of a line, as they are logically of zero width. + + - *matrixName* __delete column__ *column* + + Deletes the specified column from the matrix and shifts all columns with + higher indices one index down. + + - *matrixName* __delete columns__ *n* + + Deletes *n* columns from the right of the matrix. The value of *n* has to + satisfy the constraint "0 < *n* < [__matrixName__ __columns__]" + + - *matrixName* __delete row__ *row* + + Deletes the specified row from the matrix and shifts all row with higher + indices one index down. + + - *matrixName* __delete rows__ *n* + + Deletes *n* rows from the bottom of the matrix. The value of *n* has to + satisfy the constraint "0 < *n* < [__matrixName__ __rows__]" + + - *matrixName* __deserialize__ *serialization* + + This is the complement to __serialize__. It replaces matrix data in + *matrixName* with the matrix described by the *serialization* value. The old + contents of *matrixName* are deleted by this operation. + + - *matrixName* __destroy__ + + Destroys the matrix, including its storage space and associated command. + + - *matrixName* __format 2string__ ?*report*? + + Formats the matrix using the specified report object and returns the string + containing the result of this operation. The report has to support the + __printmatrix__ method. If no *report* is specified the system will use an + internal report definition to format the matrix. + + - *matrixName* __format 2chan__ ??*report*? *channel*? + + Formats the matrix using the specified report object and writes the string + containing the result of this operation into the channel. The report has to + support the __printmatrix2channel__ method. If no *report* is specified the + system will use an internal report definition to format the matrix. If no + *channel* is specified the system will use __stdout__. + + - *matrixName* __get cell__ *column row* + + Returns the value currently contained in the cell identified by row and + column index. + + - *matrixName* __get column__ *column* + + Returns a list containing the values from all cells in the column identified + by the index. The contents of the cell in row 0 are stored as the first + element of this list. + + - *matrixName* __get rect__ *column_tl row_tl column_br row_br* + + Returns a list of lists of cell values. The values stored in the result come + from the sub-matrix whose top-left and bottom-right cells are specified by + *column_tl, row_tl* and *column_br, row_br* resp. Note that the following + equations have to be true: "*column_tl* <= *column_br*" and "*row_tl* <= + *row_br*". The result is organized as follows: The outer list is the list of + rows, its elements are lists representing a single row. The row with the + smallest index is the first element of the outer list. The elements of the + row lists represent the selected cell values. The cell with the smallest + index is the first element in each row list. + + - *matrixName* __get row__ *row* + + Returns a list containing the values from all cells in the row identified by + the index. The contents of the cell in column 0 are stored as the first + element of this list. + + - *matrixName* __insert column__ *column* ?*values*? + + Extends the matrix by one column and then acts like __set column__ (see + below) on this new column if there were *values* supplied. Without *values* + the new cells will be set to the empty string. The new column is inserted + just before the column specified by the given index. This means, if *column* + is less than or equal to zero, then the new column is inserted at the + beginning of the matrix, before the first column. If *column* has the value + __end__, or if it is greater than or equal to the number of columns in the + matrix, then the new column is appended to the matrix, behind the last + column. The old column at the chosen index and all columns with higher + indices are shifted one index upward. + + - *matrixName* __insert row__ *row* ?*values*? + + Extends the matrix by one row and then acts like __set row__ (see below) on + this new row if there were *values* supplied. Without *values* the new cells + will be set to the empty string. The new row is inserted just before the row + specified by the given index. This means, if *row* is less than or equal to + zero, then the new row is inserted at the beginning of the matrix, before + the first row. If *row* has the value __end__, or if it is greater than or + equal to the number of rows in the matrix, then the new row is appended to + the matrix, behind the last row. The old row at that index and all rows with + higher indices are shifted one index upward. + + - *matrixName* __link__ ?-transpose? *arrayvar* + + Links the matrix to the specified array variable. This means that the + contents of all cells in the matrix is stored in the array too, with all + changes to the matrix propagated there too. The contents of the cell + *(column,row)* is stored in the array using the key *column,row*. If the + option __-transpose__ is specified the key *row,column* will be used + instead. It is possible to link the matrix to more than one array. Note that + the link is bidirectional, i.e. changes to the array are mirrored in the + matrix too. + + - *matrixName* __links__ + + Returns a list containing the names of all array variables the matrix was + linked to through a call to method __link__. + + - *matrixName* __rowheight__ *row* + + Returns the height of the specified row in lines. This is the highest number + of lines spanned by a cell over all cells in the row. + + - *matrixName* __rows__ + + Returns the number of rows currently managed by the matrix. + + - *matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __all__ *pattern* + + Searches the whole matrix for cells matching the *pattern* and returns a + list with all matches. Each item in the aforementioned list is a list itself + and contains the column and row index of the matching cell, in this order. + The results are ordered by column first and row second, both times in + ascending order. This means that matches to the left and the top of the + matrix come before matches to the right and down. + + The type of the pattern (string, glob, regular expression) is determined by + the option after the __search__ keyword. If no option is given it defaults + to __-exact__. + + If the option __-nocase__ is specified the search will be case-insensitive. + + - *matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __column__ *column pattern* + + Like __search all__, but the search is restricted to the specified column. + + - *matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __row__ *row pattern* + + Like __search all__, but the search is restricted to the specified row. + + - *matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __rect__ *column_tl row_tl column_br row_br pattern* + + Like __search all__, but the search is restricted to the specified + rectangular area of the matrix. + + - *matrixName* __serialize__ ?*column_tl row_tl column_br row_br*? + + This method serializes the sub-matrix spanned up by the rectangle + specification. In other words it returns a tcl *value* completely describing + that matrix. If no rectangle is specified the whole matrix will be + serialized. This allows, for example, the transfer of matrix objects (or + parts thereof) over arbitrary channels, persistence, etc. This method is + also the basis for both the copy constructor and the assignment operator. + + The result of this method has to be semantically identical over all + implementations of the matrix interface. This is what will enable us to copy + matrix data between different implementations of the same interface. + + The result is a list containing exactly three items. + + The first two elements of the list specify the number of rows and columns of + the matrix, in that order. The values integer numbers greater than or equal + to zero. + + The last element of the list contains the values of the matrix cells we have + serialized, in the form of a value like it is returned by the __get rect__. + However empty cells to the right and bottom of the matrix can be left out of + that value as the size information in the serialization allows the receiver + the creation of a matrix with the proper size despite the missing values. + + # A possible serialization for the matrix structure + # + # | a b d g | + # | c e | + # | f | + # + # is + # + # 3 4 {{a b d g} {c e} {f}} + + - *matrixName* __set cell__ *column row value* + + Sets the value in the cell identified by row and column index to the data in + the third argument. + + - *matrixName* __set column__ *column values* + + Sets the values in the cells identified by the column index to the elements + of the list provided as the third argument. Each element of the list is + assigned to one cell, with the first element going into the cell in row 0 + and then upward. If there are less values in the list than there are rows + the remaining rows are set to the empty string. If there are more values in + the list than there are rows the superfluous elements are ignored. The + matrix is not extended by this operation. + + - *matrixName* __set rect__ *column row values* + + Takes a list of lists of cell values and writes them into the submatrix + whose top-left cell is specified by the two indices. If the sublists of the + outerlist are not of equal length the shorter sublists will be filled with + empty strings to the length of the longest sublist. If the submatrix + specified by the top-left cell and the number of rows and columns in the + *values* extends beyond the matrix we are modifying the over-extending parts + of the values are ignored, i.e. essentially cut off. This subcommand expects + its input in the format as returned by __get rect__. + + - *matrixName* __set row__ *row values* + + Sets the values in the cells identified by the row index to the elements of + the list provided as the third argument. Each element of the list is + assigned to one cell, with the first element going into the cell in column 0 + and then upward. If there are less values in the list than there are columns + the remaining columns are set to the empty string. If there are more values + in the list than there are columns the superfluous elements are ignored. The + matrix is not extended by this operation. + + - *matrixName* __sort columns__ ?__-increasing__|__-decreasing__? *row* + + Sorts the columns in the matrix using the data in the specified *row* as the + key to sort by. The options __-increasing__ and __-decreasing__ have the + same meaning as for __lsort__. If no option is specified __-increasing__ is + assumed. + + - *matrixName* __sort rows__ ?__-increasing__|__-decreasing__? *column* + + Sorts the rows in the matrix using the data in the specified *column* as the + key to sort by. The options __-increasing__ and __-decreasing__ have the + same meaning as for __lsort__. If no option is specified __-increasing__ is + assumed. + + - *matrixName* __swap columns__ *column_a column_b* + + Swaps the contents of the two specified columns. + + - *matrixName* __swap rows__ *row_a row_b* + + Swaps the contents of the two specified rows. + + - *matrixName* __transpose__ + + Transposes the contents of the matrix, i.e. swaps rows for columns and vice + versa. + + - *matrixName* __unlink__ *arrayvar* + + Removes the link between the matrix and the specified arrayvariable, if + there is one. + +# EXAMPLES + +The examples below assume a 5x5 matrix M with the first row containing the +values 1 to 5, with 1 in the top-left cell. Each other row contains the contents +of the row above it, rotated by one cell to the right. + + % M get rect 0 0 4 4 + {{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}} + + % M set rect 1 1 {{0 0 0} {0 0 0} {0 0 0}} + % M get rect 0 0 4 4 + {{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}} + +Assuming that the style definitions in the example section of the manpage for +the package __[report](../report/report.md)__ are loaded into the interpreter +now an example which formats a matrix into a tabular report. The code filling +the matrix with data is not shown. contains useful data. + + % ::struct::matrix m + % # ... fill m with data, assume 5 columns + % ::report::report r 5 style captionedtable 1 + % m format 2string r + +---+-------------------+-------+-------+--------+ + |000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%| + +---+-------------------+-------+-------+--------+ + |001|CATCH return ok |7 |13 |53.85 | + |002|CATCH return error |68 |91 |74.73 | + |003|CATCH no catch used|7 |14 |50.00 | + |004|IF if true numeric |12 |33 |36.36 | + |005|IF elseif |15 |47 |31.91 | + | |true numeric | | | | + +---+-------------------+-------+-------+--------+ + % + % # alternate way of doing the above + % r printmatrix m + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: matrix* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[matrix](../../../../index.md#matrix) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2002-2013 Andreas Kupries ADDED embedded/md/tcllib/files/modules/struct/matrix1.md Index: embedded/md/tcllib/files/modules/struct/matrix1.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/matrix1.md @@ -0,0 +1,406 @@ + +[//000000001]: # (struct::matrix_v1 - Tcl Data Structures) +[//000000002]: # (Generated from file 'matrix1.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::matrix_v1(n) 1.2.1 tcllib "Tcl Data Structures") + +# NAME + +struct::matrix_v1 - Create and manipulate matrix objects + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [EXAMPLES](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require struct::matrix ?1.2.1? + +[__matrixName__ *option* ?*arg arg ...*?](#1) +[*matrixName* __add column__ ?*values*?](#2) +[*matrixName* __add row__ ?*values*?](#3) +[*matrixName* __add columns__ *n*](#4) +[*matrixName* __add rows__ *n*](#5) +[*matrixName* __cells__](#6) +[*matrixName* __cellsize__ *column row*](#7) +[*matrixName* __columns__](#8) +[*matrixName* __columnwidth__ *column*](#9) +[*matrixName* __delete column__ *column*](#10) +[*matrixName* __delete row__ *row*](#11) +[*matrixName* __destroy__](#12) +[*matrixName* __format 2string__ ?*report*?](#13) +[*matrixName* __format 2chan__ ??*report*? *channel*?](#14) +[*matrixName* __get cell__ *column row*](#15) +[*matrixName* __get column__ *column*](#16) +[*matrixName* __get rect__ *column_tl row_tl column_br row_br*](#17) +[*matrixName* __get row__ *row*](#18) +[*matrixName* __insert column__ *column* ?*values*?](#19) +[*matrixName* __insert row__ *row* ?*values*?](#20) +[*matrixName* __link__ ?-transpose? *arrayvar*](#21) +[*matrixName* __links__](#22) +[*matrixName* __rowheight__ *row*](#23) +[*matrixName* __rows__](#24) +[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __all__ *pattern*](#25) +[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __column__ *column pattern*](#26) +[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __row__ *row pattern*](#27) +[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __rect__ *column_tl row_tl column_br row_br pattern*](#28) +[*matrixName* __set cell__ *column row value*](#29) +[*matrixName* __set column__ *column values*](#30) +[*matrixName* __set rect__ *column row values*](#31) +[*matrixName* __set row__ *row values*](#32) +[*matrixName* __sort columns__ ?__-increasing__|__-decreasing__? *row*](#33) +[*matrixName* __sort rows__ ?__-increasing__|__-decreasing__? *column*](#34) +[*matrixName* __swap columns__ *column_a column_b*](#35) +[*matrixName* __swap rows__ *row_a row_b*](#36) +[*matrixName* __unlink__ *arrayvar*](#37) + +# DESCRIPTION + +The __::struct::matrix__ command creates a new matrix object with an associated +global Tcl command whose name is *matrixName*. This command may be used to +invoke various operations on the matrix. It has the following general form: + + - __matrixName__ *option* ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. + +A matrix is a rectangular collection of cells, i.e. organized in rows and +columns. Each cell contains exactly one value of arbitrary form. The cells in +the matrix are addressed by pairs of integer numbers, with the first (left) +number in the pair specifying the column and the second (right) number +specifying the row the cell is in. These indices are counted from 0 upward. The +special non-numeric index __end__ refers to the last row or column in the +matrix, depending on the context. Indices of the form __end__-__number__ are +counted from the end of the row or column, like they are for standard Tcl lists. +Trying to access non-existing cells causes an error. + +The matrices here are created empty, i.e. they have neither rows nor columns. +The user then has to add rows and columns as needed by his application. A +specialty of this structure is the ability to export an array-view onto its +contents. Such can be used by tkTable, for example, to link the matrix into the +display. + +The following commands are possible for matrix objects: + + - *matrixName* __add column__ ?*values*? + + Extends the matrix by one column and then acts like __setcolumn__ (see + below) on this new column if there were *values* supplied. Without *values* + the new cells will be set to the empty string. The new column is appended + immediately behind the last existing column. + + - *matrixName* __add row__ ?*values*? + + Extends the matrix by one row and then acts like __setrow__ (see below) on + this new row if there were *values* supplied. Without *values* the new cells + will be set to the empty string. The new row is appended immediately behind + the last existing row. + + - *matrixName* __add columns__ *n* + + Extends the matrix by *n* columns. The new cells will be set to the empty + string. The new columns are appended immediately behind the last existing + column. A value of *n* equal to or smaller than 0 is not allowed. + + - *matrixName* __add rows__ *n* + + Extends the matrix by *n* rows. The new cells will be set to the empty + string. The new rows are appended immediately behind the last existing row. + A value of *n* equal to or smaller than 0 is not allowed. + + - *matrixName* __cells__ + + Returns the number of cells currently managed by the matrix. This is the + product of __rows__ and __columns__. + + - *matrixName* __cellsize__ *column row* + + Returns the length of the string representation of the value currently + contained in the addressed cell. + + - *matrixName* __columns__ + + Returns the number of columns currently managed by the matrix. + + - *matrixName* __columnwidth__ *column* + + Returns the length of the longest string representation of all the values + currently contained in the cells of the addressed column if these are all + spanning only one line. For cell values spanning multiple lines the length + of their longest line goes into the computation. + + - *matrixName* __delete column__ *column* + + Deletes the specified column from the matrix and shifts all columns with + higher indices one index down. + + - *matrixName* __delete row__ *row* + + Deletes the specified row from the matrix and shifts all row with higher + indices one index down. + + - *matrixName* __destroy__ + + Destroys the matrix, including its storage space and associated command. + + - *matrixName* __format 2string__ ?*report*? + + Formats the matrix using the specified report object and returns the string + containing the result of this operation. The report has to support the + __printmatrix__ method. If no *report* is specified the system will use an + internal report definition to format the matrix. + + - *matrixName* __format 2chan__ ??*report*? *channel*? + + Formats the matrix using the specified report object and writes the string + containing the result of this operation into the channel. The report has to + support the __printmatrix2channel__ method. If no *report* is specified the + system will use an internal report definition to format the matrix. If no + *channel* is specified the system will use __stdout__. + + - *matrixName* __get cell__ *column row* + + Returns the value currently contained in the cell identified by row and + column index. + + - *matrixName* __get column__ *column* + + Returns a list containing the values from all cells in the column identified + by the index. The contents of the cell in row 0 are stored as the first + element of this list. + + - *matrixName* __get rect__ *column_tl row_tl column_br row_br* + + Returns a list of lists of cell values. The values stored in the result come + from the sub-matrix whose top-left and bottom-right cells are specified by + *column_tl, row_tl* and *column_br, row_br* resp. Note that the following + equations have to be true: "*column_tl* <= *column_br*" and "*row_tl* <= + *row_br*". The result is organized as follows: The outer list is the list of + rows, its elements are lists representing a single row. The row with the + smallest index is the first element of the outer list. The elements of the + row lists represent the selected cell values. The cell with the smallest + index is the first element in each row list. + + - *matrixName* __get row__ *row* + + Returns a list containing the values from all cells in the row identified by + the index. The contents of the cell in column 0 are stored as the first + element of this list. + + - *matrixName* __insert column__ *column* ?*values*? + + Extends the matrix by one column and then acts like __setcolumn__ (see + below) on this new column if there were *values* supplied. Without *values* + the new cells will be set to the empty string. The new column is inserted + just before the column specified by the given index. This means, if *column* + is less than or equal to zero, then the new column is inserted at the + beginning of the matrix, before the first column. If *column* has the value + __end__, or if it is greater than or equal to the number of columns in the + matrix, then the new column is appended to the matrix, behind the last + column. The old column at the chosen index and all columns with higher + indices are shifted one index upward. + + - *matrixName* __insert row__ *row* ?*values*? + + Extends the matrix by one row and then acts like __setrow__ (see below) on + this new row if there were *values* supplied. Without *values* the new cells + will be set to the empty string. The new row is inserted just before the row + specified by the given index. This means, if *row* is less than or equal to + zero, then the new row is inserted at the beginning of the matrix, before + the first row. If *row* has the value __end__, or if it is greater than or + equal to the number of rows in the matrix, then the new row is appended to + the matrix, behind the last row. The old row at that index and all rows with + higher indices are shifted one index upward. + + - *matrixName* __link__ ?-transpose? *arrayvar* + + Links the matrix to the specified array variable. This means that the + contents of all cells in the matrix is stored in the array too, with all + changes to the matrix propagated there too. The contents of the cell + *(column,row)* is stored in the array using the key *column,row*. If the + option __-transpose__ is specified the key *row,column* will be used + instead. It is possible to link the matrix to more than one array. Note that + the link is bidirectional, i.e. changes to the array are mirrored in the + matrix too. + + - *matrixName* __links__ + + Returns a list containing the names of all array variables the matrix was + linked to through a call to method __link__. + + - *matrixName* __rowheight__ *row* + + Returns the height of the specified row in lines. This is the highest number + of lines spanned by a cell over all cells in the row. + + - *matrixName* __rows__ + + Returns the number of rows currently managed by the matrix. + + - *matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __all__ *pattern* + + Searches the whole matrix for cells matching the *pattern* and returns a + list with all matches. Each item in the aforementioned list is a list itself + and contains the column and row index of the matching cell, in this order. + The results are ordered by column first and row second, both times in + ascending order. This means that matches to the left and the top of the + matrix come before matches to the right and down. + + The type of the pattern (string, glob, regular expression) is determined by + the option after the __search__ keyword. If no option is given it defaults + to __-exact__. + + If the option __-nocase__ is specified the search will be case-insensitive. + + - *matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __column__ *column pattern* + + Like __search all__, but the search is restricted to the specified column. + + - *matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __row__ *row pattern* + + Like __search all__, but the search is restricted to the specified row. + + - *matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __rect__ *column_tl row_tl column_br row_br pattern* + + Like __search all__, but the search is restricted to the specified + rectangular area of the matrix. + + - *matrixName* __set cell__ *column row value* + + Sets the value in the cell identified by row and column index to the data in + the third argument. + + - *matrixName* __set column__ *column values* + + Sets the values in the cells identified by the column index to the elements + of the list provided as the third argument. Each element of the list is + assigned to one cell, with the first element going into the cell in row 0 + and then upward. If there are less values in the list than there are rows + the remaining rows are set to the empty string. If there are more values in + the list than there are rows the superfluous elements are ignored. The + matrix is not extended by this operation. + + - *matrixName* __set rect__ *column row values* + + Takes a list of lists of cell values and writes them into the submatrix + whose top-left cell is specified by the two indices. If the sublists of the + outerlist are not of equal length the shorter sublists will be filled with + empty strings to the length of the longest sublist. If the submatrix + specified by the top-left cell and the number of rows and columns in the + *values* extends beyond the matrix we are modifying the over-extending parts + of the values are ignored, i.e. essentially cut off. This subcommand expects + its input in the format as returned by __getrect__. + + - *matrixName* __set row__ *row values* + + Sets the values in the cells identified by the row index to the elements of + the list provided as the third argument. Each element of the list is + assigned to one cell, with the first element going into the cell in column 0 + and then upward. If there are less values in the list than there are columns + the remaining columns are set to the empty string. If there are more values + in the list than there are columns the superfluous elements are ignored. The + matrix is not extended by this operation. + + - *matrixName* __sort columns__ ?__-increasing__|__-decreasing__? *row* + + Sorts the columns in the matrix using the data in the specified *row* as the + key to sort by. The options __-increasing__ and __-decreasing__ have the + same meaning as for __lsort__. If no option is specified __-increasing__ is + assumed. + + - *matrixName* __sort rows__ ?__-increasing__|__-decreasing__? *column* + + Sorts the rows in the matrix using the data in the specified *column* as the + key to sort by. The options __-increasing__ and __-decreasing__ have the + same meaning as for __lsort__. If no option is specified __-increasing__ is + assumed. + + - *matrixName* __swap columns__ *column_a column_b* + + Swaps the contents of the two specified columns. + + - *matrixName* __swap rows__ *row_a row_b* + + Swaps the contents of the two specified rows. + + - *matrixName* __unlink__ *arrayvar* + + Removes the link between the matrix and the specified arrayvariable, if + there is one. + +# EXAMPLES + +The examples below assume a 5x5 matrix M with the first row containing the +values 1 to 5, with 1 in the top-left cell. Each other row contains the contents +of the row above it, rotated by one cell to the right. + + % M getrect 0 0 4 4 + {{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}} + + % M setrect 1 1 {{0 0 0} {0 0 0} {0 0 0}} + % M getrect 0 0 4 4 + {{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}} + +Assuming that the style definitions in the example section of the manpage for +the package __[report](../report/report.md)__ are loaded into the interpreter +now an example which formats a matrix into a tabular report. The code filling +the matrix with data is not shown. contains useful data. + + % ::struct::matrix m + % # ... fill m with data, assume 5 columns + % ::report::report r 5 style captionedtable 1 + % m format 2string r + +---+-------------------+-------+-------+--------+ + |000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%| + +---+-------------------+-------+-------+--------+ + |001|CATCH return ok |7 |13 |53.85 | + |002|CATCH return error |68 |91 |74.73 | + |003|CATCH no catch used|7 |14 |50.00 | + |004|IF if true numeric |12 |33 |36.36 | + |005|IF elseif |15 |47 |31.91 | + | |true numeric | | | | + +---+-------------------+-------+-------+--------+ + % + % # alternate way of doing the above + % r printmatrix m + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: matrix* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[matrix](../../../../index.md#matrix) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2002 Andreas Kupries ADDED embedded/md/tcllib/files/modules/struct/pool.md Index: embedded/md/tcllib/files/modules/struct/pool.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/pool.md @@ -0,0 +1,409 @@ + +[//000000001]: # (struct::pool - Tcl Data Structures) +[//000000002]: # (Generated from file 'pool.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::pool(n) 1.2.3 tcllib "Tcl Data Structures") + +# NAME + +struct::pool - Create and manipulate pool objects (of discrete items) + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [POOLS AND ALLOCATION](#section2) + + - [ITEMS](#section3) + + - [POOL OBJECT COMMAND](#section4) + + - [EXAMPLES](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require struct::pool ?1.2.3? + +[__::struct::pool__ ?*poolName*? ?*maxsize*?](#1) +[__poolName__ *option* ?*arg arg ...*?](#2) +[*poolName* __add__ *itemName1* ?*itemName2 itemName3 ...*?](#3) +[*poolName* __clear__ ?__-force__?](#4) +[*poolName* __destroy__ ?__-force__?](#5) +[*poolName* __info__ *type* ?*arg*?](#6) +[*poolName* __maxsize__ ?*maxsize*?](#7) +[*poolName* __release__ *itemName*](#8) +[*poolName* __remove__ *itemName* ?__-force__?](#9) +[*poolName* __request__ itemVar ?options?](#10) + +# DESCRIPTION + +This package provides pool objects which can be used to manage finite +collections of discrete items. + + - __::struct::pool__ ?*poolName*? ?*maxsize*? + + Creates a new pool object. If no *poolName* is supplied, then the new pool + will be named pool__X__, where X is a positive integer. The optional second + argument *maxsize* has to be a positive integer indicating the maximum size + of the pool; this is the maximum number of items the pool may hold. The + default for this value is __10__. + + The pool object has an associated global Tcl command whose name is + *poolName*. This command may be used to invoke various configuration + operations on the report. It has the following general form: + + * __poolName__ *option* ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. See + section [POOL OBJECT COMMAND](#section4) for a detailed list of options + and their behaviour. + +# POOLS AND ALLOCATION + +The purpose of the pool command and the pool object command that it generates, +is to manage pools of discrete items. Examples of a pool of discrete items are: + + - the seats in a cinema, theatre, train etc.. for which visitors/travelers can + make a reservation; + + - the dynamic IP-addresses that an ISP can dole out to subscribers; + + - a car rental's collection of cars, which can be rented by customers; + + - the class rooms in a school building, which need to be scheduled; + + - the database connections available to client-threads in a web-server + application; + + - the books in a library that customers can borrow; + + - etc ... + +The common denominator in the examples is that there is a more or less fixed +number of items (seats, IP-addresses, cars, ...) that are supposed to be +allocated on a more or less regular basis. An item can be allocated only once at +a time. An item that is allocated, must be released before it can be +re-allocated. While several items in a pool are being allocated and released +continuously, the total number of items in the pool remains constant. + +Keeping track of which items are allocated, and by whom, is the purpose of the +pool command and its subordinates. + +*Pool parlance*: If we say that an item is *allocated*, it means that the item +is *busy*, *owned* or *occupied*; it is not available anymore. If an item is +*free*, it is *available*. Deallocating an item is equivalent to setting free or +releasing an item. The person or entity to which the item has been allotted is +said to own the item. + +# ITEMS + +*Discrete items* + +The __[pool](../../../../index.md#pool)__ command is designed for *discrete +items only*. Note that there are pools where allocation occurs on a non-discrete +basis, for example computer memory. There are also pools from which the shares +that are doled out are not expected to be returned, for example a charity fund +or a pan of soup from which you may receive a portion. Finally, there are even +pools from which nothing is ever allocated or returned, like a swimming pool or +a cesspool. + +*Unique item names* + +A pool cannot manage duplicate item names. Therefore, items in a pool must have +unique names. + +*Item equivalence* + +From the point of view of the manager of a pool, items are equivalent. The +manager of a pool is indifferent about which entity/person occupies a given +item. However, clients may have preferences for a particular item, based on some +item property they know. + +*Preferences* + +A future owner may have a preference for a particular item. Preference based +allocation is supported (see the __-prefer__ option to the request subcommand). +A preference for a particular item is most likely to result from variability +among features associated with the items. Note that the pool commands themselves +are not designed to manage such item properties. If item properties play a role +in an application, they should be managed separately. + +# POOL OBJECT COMMAND + +The following subcommands and corresponding arguments are available to any pool +object command. + + - *poolName* __add__ *itemName1* ?*itemName2 itemName3 ...*? + + This command adds the items on the command line to the pool. If duplicate + item names occur on the command line, an error is raised. If one or more of + the items already exist in the pool, this also is considered an error. + + - *poolName* __clear__ ?__-force__? + + Removes all items from the pool. If there are any allocated items at the + time when the command is invoked, an error is raised. This behaviour may be + modified through the __-force__ argument. If it is supplied on the command + line, the pool will be cleared regardless the allocation state of its items. + + - *poolName* __destroy__ ?__-force__? + + Destroys the pool data structure, all associated variables and the + associated pool object command. By default, the command checks whether any + items are still allocated and raises an error if such is the case. This + behaviour may be modified through the argument __-force__. If it is supplied + on the command line, the pool data structure will be destroyed regardless + allocation state of its items. + + - *poolName* __info__ *type* ?*arg*? + + Returns various information about the pool for further programmatic use. The + *type* argument indicates the type of information requested. Only the type + __allocID__ uses an additional argument. + + * __allocID__ *itemName* + + returns the allocID of the item whose name is *itemName*. Free items + have an allocation id of __-1__. + + * __allitems__ + + returns a list of all items in the pool. + + * __allocstate__ + + Returns a list of key-value pairs, where the keys are the items and the + values are the corresponding allocation id's. Free items have an + allocation id of __-1__. + + * __cursize__ + + returns the current pool size, i.e. the number of items in the pool. + + * __freeitems__ + + returns a list of items that currently are not allocated. + + * __maxsize__ + + returns the maximum size of the pool. + + - *poolName* __maxsize__ ?*maxsize*? + + Sets or queries the maximum size of the pool, depending on whether the + *maxsize* argument is supplied or not. If *maxsize* is supplied, the maximum + size of the pool will be set to that value. If no argument is supplied, the + current maximum size of the pool is returned. In this variant, the command + is an alias for: + + __poolName info maxsize__. + + The *maxsize* argument has to be a positive integer. + + - *poolName* __release__ *itemName* + + Releases the item whose name is *itemName* that was allocated previously. An + error is raised if the item was not allocated at the time when the command + was issued. + + - *poolName* __remove__ *itemName* ?__-force__? + + Removes the item whose name is *itemName* from the pool. If the item was + allocated at the time when the command was invoked, an error is raised. This + behaviour may be modified through the optional argument __-force__. If it is + supplied on the command line, the item will be removed regardless its + allocation state. + + - *poolName* __request__ itemVar ?options? + + Handles a request for an item, taking into account a possible preference for + a particular item. There are two possible outcomes depending on the + availability of items: + + The request is honoured, an item is allocated and the variable whose name is + passed with the argument *itemVar* will be set to the name of the item that + was allocated. The command returns 1. + + The request is denied. No item is allocated. The variable whose name is + itemVar is not set. Attempts to read *itemVar* may raise an error if the + variable was not defined before issuing the request. The command returns 0. + + The return values from this command are meant to be inspected. The examples + below show how to do this. Failure to check the return value may result in + erroneous behaviour. If no preference for a particular item is supplied + through the option __-prefer__ (see below), then all requests are honoured + as long as items are available. + + The following options are supported: + + * __-allocID__ *allocID* + + If the request is honoured, an item will be allocated to the entity + identified by allocID. If the allocation state of an item is queried, it + is this allocation ID that will be returned. If the option __-allocID__ + is not supplied, the item will be given to and owned by __dummyID__. + Allocation id's may be anything except the value -1, which is reserved + for free items. + + * __-prefer__ *preferredItem* + + This option modifies the allocation strategy as follows: If the item + whose name is *preferredItem* is not allocated at the time when the + command is invoked, the request is honoured (return value is 1). If the + item was allocated at the time when the command was invoked, the request + is denied (return value is 0). + +# EXAMPLES + +Two examples are provided. The first one mimics a step by step interactive tclsh +session, where each step is explained. The second example shows the usage in a +server application that talks to a back-end application. + +*Example 1* + +This example presents an interactive tclsh session which considers the case of a +Car rental's collection of cars. Ten steps explain its usage in chronological +order, from the creation of the pool, via the most important stages in the usage +of a pool, to the final destruction. + +*Note aside:* + +In this example, brand names are used to label the various items. However, a +brand name could be regarded as a property of an item. Because the pool command +is not designed to manage properties of items, they need to be managed +separately. In the latter case the items should be labeled with more neutral +names such as: car1, car2, car3 , etc ... and a separate database or array +should hold the brand names associated with the car labels. + + 1. Load the package into an interpreter + % package require pool + 0.1 + + 2. Create a pool object called `CarPool' with a maximum size of 55 items (cars): + % pool CarPool 55 + CarPool + + 4. Add items to the pool: + % CarPool add Toyota Trabant Chrysler1 Chrysler2 Volkswagen + + 5. Somebody crashed the Toyota. Remove it from the pool as follows: + % CarPool remove Toyota + + 6. Acquired a new car for the pool. Add it as follows: + % CarPool add Nissan + + 7. Check whether the pool was adjusted correctly: + % CarPool info allitems + Trabant Chrysler1 Chrysler2 Volkswagen Nissan + +Suspend the interactive session temporarily, and show the programmatic use of +the request subcommand: + + # Mrs. Swift needs a car. She doesn't have a preference for a + # particular car. We'll issue a request on her behalf as follows: + if { [CarPool request car -allocID "Mrs. Swift"] } { + # request was honoured, process the variable `car' + puts "$car has been allocated to [CarPool info allocID $car]." + } else { + # request was denied + puts "No car available." + } + +Note how the __if__ command uses the value returned by the __request__ +subcommand. + + # Suppose Mr. Wiggly has a preference for the Trabant: + if { [CarPool request car -allocID "Mr. Wiggly" -prefer Trabant] } { + # request was honoured, process the variable `car' + puts "$car has been allocated to [CarPool info allocID $car]." + } else { + # request was denied + puts "The Trabant was not available." + } + +Resume the interactive session: + + 8. When the car is returned then you can render it available by: + % CarPool release Trabant + + 9. When done, you delete the pool. + % CarPool destroy + Couldn't destroy `CarPool' because some items are still allocated. + + Oops, forgot that Mrs. Swift still occupies a car. + + 10. We force the destruction of the pool as follows: + % CarPool destroy -force + +*Example 2* + +This example describes the case from which the author's need for pool management +originated. It is an example of a server application that receives requests from +client applications. The client requests are dispatched onto a back-end +application before being returned to the client application. In many cases there +are a few equivalent instances of back-end applications to which a client +request may be passed along. The file descriptors that identify the channels to +these back-end instances make up a pool of connections. A particular connection +may be allocated to just one client request at a time. + + # Create the pool of connections (pipes) + set maxpipes 10 + pool Pipes $maxpipes + for {set i 0} {$i < $maxpipes} {incr i} { + set fd [open "|backendApplication" w+] + Pipes add $fd + } + + # A client request comes in. The request is identified as `clientX'. + # Dispatch it onto an instance of a back-end application + if { [Pipes request fd -allocID clientX] } { + # a connection was allocated + # communicate to the back-end application via the variable `fd' + puts $fd "someInstruction" + # ...... etc. + } else { + # all connections are currently occupied + # store the client request in a queue for later processing, + # or return a 'Server busy' message to the client. + } + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: pool* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[discrete items](../../../../index.md#discrete_items), +[finite](../../../../index.md#finite), [pool](../../../../index.md#pool), +[struct](../../../../index.md#struct) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2002, Erik Leunissen ADDED embedded/md/tcllib/files/modules/struct/prioqueue.md Index: embedded/md/tcllib/files/modules/struct/prioqueue.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/prioqueue.md @@ -0,0 +1,145 @@ + +[//000000001]: # (struct::prioqueue - Tcl Data Structures) +[//000000002]: # (Generated from file 'prioqueue.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::prioqueue(n) 1.4 tcllib "Tcl Data Structures") + +# NAME + +struct::prioqueue - Create and manipulate prioqueue objects + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require struct::prioqueue ?1.4? + +[__::struct::prioqueue__ ?__-ascii|-dictionary|-integer|-real__? ?*prioqueueName*?](#1) +[*prioqueueName* __option__ ?*arg arg ...*?](#2) +[*prioqueueName* __clear__](#3) +[*prioqueueName* __[remove](../../../../index.md#remove)__ *item*](#4) +[*prioqueueName* __destroy__](#5) +[*prioqueueName* __get__ ?*count*?](#6) +[*prioqueueName* __peek__ ?*count*?](#7) +[*prioqueueName* __peekpriority__ ?*count*?](#8) +[*prioqueueName* __put__ *item prio* ?*item prio ...*?](#9) +[*prioqueueName* __size__](#10) + +# DESCRIPTION + +This package implements a simple priority queue using nested tcl lists. + +The command __::struct::prioqueue__ creates a new priority queue with default +priority key type *-integer*. This means that keys given to the __put__ +subcommand must have this type. + +This also sets the priority ordering. For key types *-ascii* and *-dictionary* +the data is sorted in ascending order (as with __lsort__ *-increasing*), thereas +for *-integer* and *-real* the data is sorted in descending order (as with +__lsort__ *-decreasing*). + +Prioqueue names are unrestricted, but may be recognized as options if no +priority type is given. + + - __::struct::prioqueue__ ?__-ascii|-dictionary|-integer|-real__? ?*prioqueueName*? + + The __::struct::prioqueue__ command creates a new prioqueue object with an + associated global Tcl command whose name is *prioqueueName*. This command + may be used to invoke various operations on the prioqueue. It has the + following general form: + + - *prioqueueName* __option__ ?*arg arg ...*? + + __option__ and the *arg*s determine the exact behavior of the command. The + following commands are possible for prioqueue objects: + + - *prioqueueName* __clear__ + + Remove all items from the prioqueue. + + - *prioqueueName* __[remove](../../../../index.md#remove)__ *item* + + Remove the selected item from this priority queue. + + - *prioqueueName* __destroy__ + + Destroy the prioqueue, including its storage space and associated command. + + - *prioqueueName* __get__ ?*count*? + + Return the front *count* items of the prioqueue (but not their priorities) + and remove them from the prioqueue. If *count* is not specified, it defaults + to 1. If *count* is 1, the result is a simple string; otherwise, it is a + list. If specified, *count* must be greater than or equal to 1. If there are + no or too few items in the prioqueue, this command will throw an error. + + - *prioqueueName* __peek__ ?*count*? + + Return the front *count* items of the prioqueue (but not their priorities), + without removing them from the prioqueue. If *count* is not specified, it + defaults to 1. If *count* is 1, the result is a simple string; otherwise, it + is a list. If specified, *count* must be greater than or equal to 1. If + there are no or too few items in the queue, this command will throw an + error. + + - *prioqueueName* __peekpriority__ ?*count*? + + Return the front *count* items priority keys, without removing them from the + prioqueue. If *count* is not specified, it defaults to 1. If *count* is 1, + the result is a simple string; otherwise, it is a list. If specified, + *count* must be greater than or equal to 1. If there are no or too few items + in the queue, this command will throw an error. + + - *prioqueueName* __put__ *item prio* ?*item prio ...*? + + Put the *item* or items specified into the prioqueue. *prio* must be a valid + priority key for this type of prioqueue, otherwise an error is thrown and no + item is added. Items are inserted at their priority ranking. Items with + equal priority are added in the order they were added. + + - *prioqueueName* __size__ + + Return the number of items in the prioqueue. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: prioqueue* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[ordered list](../../../../index.md#ordered_list), +[prioqueue](../../../../index.md#prioqueue), [priority +queue](../../../../index.md#priority_queue) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2003 Michael Schlenker ADDED embedded/md/tcllib/files/modules/struct/queue.md Index: embedded/md/tcllib/files/modules/struct/queue.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/queue.md @@ -0,0 +1,122 @@ + +[//000000001]: # (struct::queue - Tcl Data Structures) +[//000000002]: # (Generated from file 'queue.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::queue(n) 1.4.5 tcllib "Tcl Data Structures") + +# NAME + +struct::queue - Create and manipulate queue objects + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.4 +package require struct::queue ?1.4.5? + +[*queueName* __option__ ?*arg arg ...*?](#1) +[*queueName* __clear__](#2) +[*queueName* __destroy__](#3) +[*queueName* __get__ ?*count*?](#4) +[*queueName* __peek__ ?*count*?](#5) +[*queueName* __put__ *item* ?*item ...*?](#6) +[*queueName* __unget__ *item*](#7) +[*queueName* __size__](#8) + +# DESCRIPTION + +The __::struct__ namespace contains a commands for processing finite queues. + +It exports a single command, __::struct::queue__. All functionality provided +here can be reached through a subcommand of this command. + +*Note:* As of version 1.4.1 of this package a critcl based C implementation is +available. This implementation however requires Tcl 8.4 to run. + +The __::struct::queue__ command creates a new queue object with an associated +global Tcl command whose name is *queueName*. This command may be used to invoke +various operations on the queue. It has the following general form: + + - *queueName* __option__ ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. The + following commands are possible for queue objects: + + - *queueName* __clear__ + + Remove all items from the queue. + + - *queueName* __destroy__ + + Destroy the queue, including its storage space and associated command. + + - *queueName* __get__ ?*count*? + + Return the front *count* items of the queue and remove them from the queue. + If *count* is not specified, it defaults to 1. If *count* is 1, the result + is a simple string; otherwise, it is a list. If specified, *count* must be + greater than or equal to 1. If there are not enough items in the queue to + fulfull the request, this command will throw an error. + + - *queueName* __peek__ ?*count*? + + Return the front *count* items of the queue, without removing them from the + queue. If *count* is not specified, it defaults to 1. If *count* is 1, the + result is a simple string; otherwise, it is a list. If specified, *count* + must be greater than or equal to 1. If there are not enough items in the + queue to fulfull the request, this command will throw an error. + + - *queueName* __put__ *item* ?*item ...*? + + Put the *item* or items specified into the queue. If more than one *item* is + given, they will be added in the order they are listed. + + - *queueName* __unget__ *item* + + Put the *item* into the queue, at the front, i.e. before any other items + already in the queue. This makes this operation the complement to the method + __get__. + + - *queueName* __size__ + + Return the number of items in the queue. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: queue* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[graph](../../../../index.md#graph), [list](../../../../index.md#list), +[matrix](../../../../index.md#matrix), [pool](../../../../index.md#pool), +[prioqueue](../../../../index.md#prioqueue), +[record](../../../../index.md#record), [set](../../../../index.md#set), +[skiplist](../../../../index.md#skiplist), [stack](../../../../index.md#stack), +[tree](../../../../index.md#tree) + +# CATEGORY + +Data structures ADDED embedded/md/tcllib/files/modules/struct/record.md Index: embedded/md/tcllib/files/modules/struct/record.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/record.md @@ -0,0 +1,391 @@ + +[//000000001]: # (struct::record - Tcl Data Structures) +[//000000002]: # (Generated from file 'record.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::record(n) 1.2.1 tcllib "Tcl Data Structures") + +# NAME + +struct::record - Define and create records (similar to 'C' structures) + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [RECORD MEMBERS](#section2) + + - [RECORD COMMAND](#section3) + + - [INSTANCE COMMAND](#section4) + + - [EXAMPLES](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require struct::record ?1.2.1? + +[__record define__ *recordName* *recordMembers* ?*instanceName1 instanceName2 ...*?](#1) +[__record show__ *record*](#2) +[__record show__ *instances* *recordName*](#3) +[__record show__ *members* *recordName*](#4) +[__record show__ *values* *instanceName*](#5) +[__record exists__ *record* *recordName*](#6) +[__record exists__ *instance* *instanceName*](#7) +[__record delete__ *record* *recordName*](#8) +[__record delete__ *instance* *instanceName*](#9) +[*recordName* __*instanceName|#auto*__ ?*-member1 value1 -member2 value2 ...*?](#10) +[*instanceName* __cget__ ?*-member1 -member2 ...*?](#11) +[*instanceName* __configure__ ?*-member1 value1 -member2 value2 ...*?](#12) + +# DESCRIPTION + +The __::struct::record__ package provides a mechanism to group variables +together as one data structure, similar to a 'C' structure. The members of a +record can be variables or other records. However, a record can not contain +circular record, i.e. records that contain the same record as a member. + +This package was structured so that it is very similar to how Tk objects work. +Each record definition creates a record object that encompasses that definition. +Subsequently, that record object can create instances of that record. These +instances can then be manipulated with the __cget__ and __configure__ methods. + +The package only contains one top level command, but several sub commands (see +below). It also obeys the namespace in which the record was define, hence the +objects returned are fully qualified. + + - __record define__ *recordName* *recordMembers* ?*instanceName1 instanceName2 ...*? + + Defines a record. *recordName* is the name of the record, and is also used + as an object command. This object command is used to create instances of the + record definition. *recordMembers* are the members of the record that make + up the record definition. These are variables and other record. If optional + *instanceName* args are given, then an instance is generated after the + definition is created for each *instanceName*. + + - __record show__ *record* + + Returns a list of records that have been defined. + + - __record show__ *instances* *recordName* + + Returns the instances that have been instantiated by *recordName*. + + - __record show__ *members* *recordName* + + Returns the members that are defined for record *recordName*. It returns the + same format as how the records were defined. + + - __record show__ *values* *instanceName* + + Returns a list of values that are set for the instance *instanceName*. The + output is a list of key/value pairs. If there are nested records, then the + values of the nested records will itself be a list. + + - __record exists__ *record* *recordName* + + Tests for the existence of a *record* with the name *recordName*. + + - __record exists__ *instance* *instanceName* + + Tests for the existence of a *instance* with the name *instanceName*. + + - __record delete__ *record* *recordName* + + Deletes *recordName*, and all instances of *recordName*. It will return an + error if the record does not exist. + + - __record delete__ *instance* *instanceName* + + Deletes *instance* with the name of *instanceName*. It will return an error + if the instance does not exist. + +# RECORD MEMBERS + +Record members can either be variables, or other records, However, the same +record can not be nested witin itself (circular). To define a nested record, you +need to specify the __record__ keyword, along the with name of the record, and +the name of the instance of that nested record. For example, it would look like +this: + + # this is the nested record + record define mynestedrecord { + nest1 + nest2 + } + + # This is the main record + record define myrecord { + mem1 + mem2 + {record mynestedrecord mem3} + } + +You can also assign default or initial values to the members of a record, by +enclosing the member entry in braces: + + record define myrecord { + mem1 + {mem2 5} + } + +All instances created from this record definition, will initially have 5 as the +value for *mem2*. If no default is given, then the value will be the empty +string. + +*Getting Values* + +To get a value of a member, there are several ways to do this. + + 1. To get a member value, then use the instance built-in __cget__ method: + + *instanceName* __cget__ -mem1 + + 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* + +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* + +In the original implementation, access was done by using dot notation similar to +how 'C' structures are accessed. However, there was a concensus to make the +interface more Tcl like, which made sense. However, the original alias access +still exists. It might prove to be helpful to some. + +Basically, for every member of every instance, an alias is created. This alias +is used to get and set values for that member. An example will illustrate the +point, using the above defined records: + + # Create an instance first + % myrecord inst1 + ::inst1 + % # To get a member of an instance, just use the + % # alias (it behaves like a Tcl command): + % inst1.mem1 + % + % # To set a member via the alias, just include + % # a value (optionally the equal sign - syntactic sugar) + % inst1.mem1 = 5 + 5 + % inst1.mem1 + 5 + % # For nested records, just continue with the + % # dot notation (note no equal sign) + % inst1.mem3.nest1 10 + 10 + % inst1.mem3.nest1 + 10 + % # just the instance by itself gives all + % # member/values pairs for that instance + % inst1 + -mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}} + % # and to get all members within the nested record + % inst1.mem3 + -nest1 10 -nest2 {} + % + +# RECORD COMMAND + +The following subcommands and corresponding arguments are available to any +record command: + + - *recordName* __*instanceName|#auto*__ ?*-member1 value1 -member2 value2 ...*? + + Using the *recordName* object command that was created from the record + definition, instances of the record definition can be created. Once a + instance is created, then it inherits the members of the record definition, + very similar to how objects work. During instance generation, an object + command for the instance is created as well, using *instanceName*. This + object command is used to access the data members of the instance. During + the instantiation, values for that instance can be given, *but* all values + must be given, and be given in key/value pairs. Nested records, need to be + in list format. + + Optionally, *#auto* can be used in place of *instanceName*. When #auto is + used, then a instance name will automatically be generated, of the form + recordName, where is a unique integer (starting at 0) + that is generated. + +# INSTANCE COMMAND + +The following subcommands and corresponding arguments are available to any +record instance command: + + - *instanceName* __cget__ ?*-member1 -member2 ...*? + + Each instance has the sub command __cget__ associated with it. This is very + similar to how Tk widget's cget command works. It queries the values of the + member for that particular instance. If no arguments are given, then a + key/value list is returned. + + - *instanceName* __configure__ ?*-member1 value1 -member2 value2 ...*? + + Each instance has the sub command __configure__ associated with it. This is + very similar to how Tk widget's configure command works. It sets the values + of the particular member for that particular instance. If no arguments are + given, then a key/value list is returned. + +# EXAMPLES + +Two examples are provided to give an good illustration on how to use this +package. + +*Example 1* + +Probably the most obvious example would be to hold contact information, such as +addresses, phone numbers, comments, etc. Since a person can have multiple phone +numbers, multiple email addresses, etc, we will use nested records to define +these. So, the first thing we do is define the nested records: + + ## + ## This is an interactive example, to see what is + ## returned by each command as well. + ## + + % namespace import ::struct::record::* + + % # define a nested record. Notice that country has default 'USA'. + % record define locations { + street + street2 + city + state + zipcode + {country USA} + phone + } + ::locations + % # Define the main record. Notice that it uses the location record twice. + % record define contacts { + first + middle + last + {record locations home} + {record locations work} + } + ::contacts + % # Create an instance for the contacts record. + % contacts cont1 + ::cont1 + % # Display some introspection values + % record show records + ::contacts ::locations + % # + % record show values cont1 + -first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} + % # + % record show instances contacts + ::cont1 + % # + % cont1 config + -first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} + % # + % cont1 cget + -first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} + % # copy one record to another record + % record define contacts2 [record show members contacts] + ::contacts2 + % record show members contacts2 + first middle last {record locations home} {record locations work} + % record show members contacts + first middle last {record locations home} {record locations work} + % + +*Example 1* + +This next example just illustrates a simple linked list + + % # define a very simple record for linked list + % record define llist { + value + next + } + ::llist + % llist lstart + ::lstart + % lstart config -value 1 -next [llist #auto] + % [lstart cget -next] config -value 2 -next [llist #auto] + % [[lstart cget -next] cget -next] config -value 3 -next "end" + % set next lstart + lstart + % while 1 { + lappend values [$next cget -value] + set next [$next cget -next] + if {[string match "end" $next]} {break} + } + % puts "$values" + 1 2 3 + % # cleanup linked list + % # We could just use delete record llist also + % foreach I [record show instances llist] { + record delete instance $I + } + % record show instances llist + % + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: record* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[data structures](../../../../index.md#data_structures), +[record](../../../../index.md#record), [struct](../../../../index.md#struct) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2002, Brett Schwarz ADDED embedded/md/tcllib/files/modules/struct/skiplist.md Index: embedded/md/tcllib/files/modules/struct/skiplist.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/skiplist.md @@ -0,0 +1,117 @@ + +[//000000001]: # (struct::skiplist - Tcl Data Structures) +[//000000002]: # (Generated from file 'skiplist.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::skiplist(n) 1.3 tcllib "Tcl Data Structures") + +# NAME + +struct::skiplist - Create and manipulate skiplists + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require struct::skiplist ?1.3? + +[__skiplistName__ *option* ?*arg arg ...*?](#1) +[*skiplistName* __delete__ *node* ?*node*...?](#2) +[*skiplistName* __destroy__](#3) +[*skiplistName* __insert__ *key value*](#4) +[*skiplistName* __search__ *node* ?__-key__ *key*?](#5) +[*skiplistName* __size__](#6) +[*skiplistName* __walk__ *cmd*](#7) + +# DESCRIPTION + +The __::struct::skiplist__ command creates a new skiplist object with an +associated global Tcl command whose name is *skiplistName*. This command may be +used to invoke various operations on the skiplist. It has the following general +form: + + - __skiplistName__ *option* ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. + +Skip lists are an alternative data structure to binary trees. They can be used +to maintain ordered lists over any sequence of insertions and deletions. Skip +lists use randomness to achieve probabilistic balancing, and as a result the +algorithms for insertion and deletion in skip lists are much simpler and faster +than those for binary trees. + +To read more about skip lists see Pugh, William. *Skip lists: a probabilistic +alternative to balanced trees* In: Communications of the ACM, June 1990, 33(6) +668-676. + +Currently, the key can be either a number or a string, and comparisons are +performed with the built in greater than operator. The following commands are +possible for skiplist objects: + + - *skiplistName* __delete__ *node* ?*node*...? + + Remove the specified nodes from the skiplist. + + - *skiplistName* __destroy__ + + Destroy the skiplist, including its storage space and associated command. + + - *skiplistName* __insert__ *key value* + + Insert a node with the given *key* and *value* into the skiplist. If a node + with that key already exists, then the that node's value is updated and its + node level is returned. Otherwise a new node is created and 0 is returned. + + - *skiplistName* __search__ *node* ?__-key__ *key*? + + Search for a given key in a skiplist. If not found then 0 is returned. If + found, then a two element list of 1 followed by the node's value is retuned. + + - *skiplistName* __size__ + + Return a count of the number of nodes in the skiplist. + + - *skiplistName* __walk__ *cmd* + + Walk the skiplist from the first node to the last. At each node, the command + *cmd* will be evaluated with the key and value of the current node appended. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: skiplist* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[skiplist](../../../../index.md#skiplist) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2000 Keith Vetter ADDED embedded/md/tcllib/files/modules/struct/stack.md Index: embedded/md/tcllib/files/modules/struct/stack.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/stack.md @@ -0,0 +1,141 @@ + +[//000000001]: # (struct::stack - Tcl Data Structures) +[//000000002]: # (Generated from file 'stack.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::stack(n) 1.5.3 tcllib "Tcl Data Structures") + +# NAME + +struct::stack - Create and manipulate stack objects + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.4 +package require struct::stack ?1.5.3? + +[*stackName* __option__ ?*arg arg ...*?](#1) +[*stackName* __clear__](#2) +[*stackName* __destroy__](#3) +[*stackName* __get__](#4) +[*stackName* __getr__](#5) +[*stackName* __peek__ ?*count*?](#6) +[*stackName* __peekr__ ?*count*?](#7) +[*stackName* __trim__ ?*newsize*?](#8) +[*stackName* __trim*__ ?*newsize*?](#9) +[*stackName* __pop__ ?*count*?](#10) +[*stackName* __push__ *item* ?*item...*?](#11) +[*stackName* __size__](#12) + +# DESCRIPTION + +The __::struct__ namespace contains a commands for processing finite stacks. + +It exports a single command, __::struct::stack__. All functionality provided +here can be reached through a subcommand of this command. + +*Note:* As of version 1.3.3 of this package a critcl based C implementation is +available. This implementation however requires Tcl 8.4 to run. + +The __::struct::stack__ command creates a new stack object with an associated +global Tcl command whose name is *stackName*. This command may be used to invoke +various operations on the stack. It has the following general form: + + - *stackName* __option__ ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. The + following commands are possible for stack objects: + + - *stackName* __clear__ + + Remove all items from the stack. + + - *stackName* __destroy__ + + Destroy the stack, including its storage space and associated command. + + - *stackName* __get__ + + Returns the whole contents of the stack as a list, without removing them + from the stack. + + - *stackName* __getr__ + + A variant of __get__, which returns the contents in reversed order. + + - *stackName* __peek__ ?*count*? + + Return the top *count* items of the stack, without removing them from the + stack. If *count* is not specified, it defaults to 1. If *count* is 1, the + result is a simple string; otherwise, it is a list. If specified, *count* + must be greater than or equal to 1. If there are not enoughs items on the + stack to fulfull the request, this command will throw an error. + + - *stackName* __peekr__ ?*count*? + + A variant of __peek__, which returns the items in reversed order. + + - *stackName* __trim__ ?*newsize*? + + Shrinks the stack to contain at most *newsize* elements and returns a list + containing the elements which were removed. Nothing is done if the stack is + already at the specified size, or smaller. In that case the result is the + empty list. + + - *stackName* __trim*__ ?*newsize*? + + A variant of __trim__ which performs the shrinking, but does not return the + removed elements. + + - *stackName* __pop__ ?*count*? + + Return the top *count* items of the stack, and remove them from the stack. + If *count* is not specified, it defaults to 1. If *count* is 1, the result + is a simple string; otherwise, it is a list. If specified, *count* must be + greater than or equal to 1. If there are not enoughs items on the stack to + fulfull the request, this command will throw an error. + + - *stackName* __push__ *item* ?*item...*? + + Push the *item* or items specified onto the stack. If more than one *item* + is given, they will be pushed in the order they are listed. + + - *stackName* __size__ + + Return the number of items on the stack. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: stack* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[graph](../../../../index.md#graph), [matrix](../../../../index.md#matrix), +[queue](../../../../index.md#queue), [tree](../../../../index.md#tree) + +# CATEGORY + +Data structures ADDED embedded/md/tcllib/files/modules/struct/struct_list.md Index: embedded/md/tcllib/files/modules/struct/struct_list.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/struct_list.md @@ -0,0 +1,700 @@ + +[//000000001]: # (struct::list - Tcl Data Structures) +[//000000002]: # (Generated from file 'struct_list.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::list(n) 1.8.4 tcllib "Tcl Data Structures") + +# NAME + +struct::list - Procedures for manipulating lists + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [LONGEST COMMON SUBSEQUENCE AND FILE COMPARISON](#section3) + + - [TABLE JOIN](#section4) + + - [REFERENCES](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require struct::list ?1.8.4? + +[__::struct::list__ __longestCommonSubsequence__ *sequence1* *sequence2* ?*maxOccurs*?](#1) +[__::struct::list__ __longestCommonSubsequence2__ *sequence1 sequence2* ?*maxOccurs*?](#2) +[__::struct::list__ __lcsInvert__ *lcsData* *len1* *len2*](#3) +[__::struct::list__ __lcsInvert2__ *lcs1* *lcs2* *len1* *len2*](#4) +[__::struct::list__ __lcsInvertMerge__ *lcsData* *len1* *len2*](#5) +[__::struct::list__ __lcsInvertMerge2__ *lcs1* *lcs2* *len1* *len2*](#6) +[__::struct::list__ __reverse__ *sequence*](#7) +[__::struct::list__ __shuffle__ *list*](#8) +[__::struct::list__ __assign__ *sequence* *varname* ?*varname*?...](#9) +[__::struct::list__ __flatten__ ?__-full__? ?__--__? *sequence*](#10) +[__::struct::list__ __map__ *sequence* *cmdprefix*](#11) +[__::struct::list__ __mapfor__ *var* *sequence* *script*](#12) +[__::struct::list__ __filter__ *sequence* *cmdprefix*](#13) +[__::struct::list__ __filterfor__ *var* *sequence* *expr*](#14) +[__::struct::list__ __split__ *sequence* *cmdprefix* ?*passVar* *failVar*?](#15) +[__::struct::list__ __fold__ *sequence* *initialvalue* *cmdprefix*](#16) +[__::struct::list__ __shift__ *listvar*](#17) +[__::struct::list__ __iota__ *n*](#18) +[__::struct::list__ __equal__ *a* *b*](#19) +[__::struct::list__ __repeat__ *size* *element1* ?*element2* *element3*...?](#20) +[__::struct::list__ __repeatn__ *value* *size*...](#21) +[__::struct::list__ __dbJoin__ ?__-inner__|__-left__|__-right__|__-full__? ?__-keys__ *varname*? {*keycol* *table*}...](#22) +[__::struct::list__ __dbJoinKeyed__ ?__-inner__|__-left__|__-right__|__-full__? ?__-keys__ *varname*? *table*...](#23) +[__::struct::list__ __swap__ *listvar* *i* *j*](#24) +[__::struct::list__ __firstperm__ *list*](#25) +[__::struct::list__ __nextperm__ *perm*](#26) +[__::struct::list__ __permutations__ *list*](#27) +[__::struct::list__ __foreachperm__ *var* *list* *body*](#28) + +# DESCRIPTION + +The __::struct::list__ namespace contains several useful commands for processing +Tcl lists. Generally speaking, they implement algorithms more complex or +specialized than the ones provided by Tcl itself. + +It exports only a single command, __struct::list__. All functionality provided +here can be reached through a subcommand of this command. + +# COMMANDS + + - __::struct::list__ __longestCommonSubsequence__ *sequence1* *sequence2* ?*maxOccurs*? + + Returns the longest common subsequence of elements in the two lists + *sequence1* and *sequence2*. If the *maxOccurs* parameter is provided, the + common subsequence is restricted to elements that occur no more than + *maxOccurs* times in *sequence2*. + + The return value is a list of two lists of equal length. The first sublist + is of indices into *sequence1*, and the second sublist is of indices into + *sequence2*. Each corresponding pair of indices corresponds to equal + elements in the sequences; the sequence returned is the longest possible. + + - __::struct::list__ __longestCommonSubsequence2__ *sequence1 sequence2* ?*maxOccurs*? + + Returns an approximation to the longest common sequence of elements in the + two lists *sequence1* and *sequence2*. If the *maxOccurs* parameter is + omitted, the subsequence computed is exactly the longest common subsequence; + otherwise, the longest common subsequence is approximated by first + determining the longest common sequence of only those elements that occur no + more than *maxOccurs* times in *sequence2*, and then using that result to + align the two lists, determining the longest common subsequences of the + sublists between the two elements. + + As with __longestCommonSubsequence__, the return value is a list of two + lists of equal length. The first sublist is of indices into *sequence1*, and + the second sublist is of indices into *sequence2*. Each corresponding pair + of indices corresponds to equal elements in the sequences. The sequence + approximates the longest common subsequence. + + - __::struct::list__ __lcsInvert__ *lcsData* *len1* *len2* + + This command takes a description of a longest common subsequence + (*lcsData*), inverts it, and returns the result. Inversion means here that + as the input describes which parts of the two sequences are identical the + output describes the differences instead. + + To be fully defined the lengths of the two sequences have to be known and + are specified through *len1* and *len2*. + + The result is a list where each element describes one chunk of the + differences between the two sequences. This description is a list containing + three elements, a type and two pairs of indices into *sequence1* and + *sequence2* respectively, in this order. The type can be one of three + values: + + * __added__ + + Describes an addition. I.e. items which are missing in *sequence1* can + be found in *sequence2*. The pair of indices into *sequence1* describes + where the added range had been expected to be in *sequence1*. The first + index refers to the item just before the added range, and the second + index refers to the item just after the added range. The pair of indices + into *sequence2* describes the range of items which has been added to + it. The first index refers to the first item in the range, and the + second index refers to the last item in the range. + + * __deleted__ + + Describes a deletion. I.e. items which are in *sequence1* are missing + from *sequence2*. The pair of indices into *sequence1* describes the + range of items which has been deleted. The first index refers to the + first item in the range, and the second index refers to the last item in + the range. The pair of indices into *sequence2* describes where the + deleted range had been expected to be in *sequence2*. The first index + refers to the item just before the deleted range, and the second index + refers to the item just after the deleted range. + + * __changed__ + + Describes a general change. I.e a range of items in *sequence1* has been + replaced by a different range of items in *sequence2*. The pair of + indices into *sequence1* describes the range of items which has been + replaced. The first index refers to the first item in the range, and the + second index refers to the last item in the range. The pair of indices + into *sequence2* describes the range of items replacing the original + range. Again the first index refers to the first item in the range, and + the second index refers to the last item in the range. + + sequence 1 = {a b r a c a d a b r a} + lcs 1 = {1 2 4 5 8 9 10} + lcs 2 = {0 1 3 4 5 6 7} + sequence 2 = {b r i c a b r a c} + + Inversion = {{deleted {0 0} {-1 0}} + {changed {3 3} {2 2}} + {deleted {6 7} {4 5}} + {added {10 11} {8 8}}} + + *Notes:* + + An index of __-1__ in a *deleted* chunk refers to just before the first + element of the second sequence. + + Also an index equal to the length of the first sequence in an *added* chunk + refers to just behind the end of the sequence. + + - __::struct::list__ __lcsInvert2__ *lcs1* *lcs2* *len1* *len2* + + Similar to __lcsInvert__. Instead of directly taking the result of a call to + __longestCommonSubsequence__ this subcommand expects the indices for the two + sequences in two separate lists. + + - __::struct::list__ __lcsInvertMerge__ *lcsData* *len1* *len2* + + Similar to __lcsInvert__. It returns essentially the same structure as that + command, except that it may contain chunks of type __unchanged__ too. + + These new chunks describe the parts which are unchanged between the two + sequences. This means that the result of this command describes both the + changed and unchanged parts of the two sequences in one structure. + + sequence 1 = {a b r a c a d a b r a} + lcs 1 = {1 2 4 5 8 9 10} + lcs 2 = {0 1 3 4 5 6 7} + sequence 2 = {b r i c a b r a c} + + Inversion/Merge = {{deleted {0 0} {-1 0}} + {unchanged {1 2} {0 1}} + {changed {3 3} {2 2}} + {unchanged {4 5} {3 4}} + {deleted {6 7} {4 5}} + {unchanged {8 10} {5 7}} + {added {10 11} {8 8}}} + + - __::struct::list__ __lcsInvertMerge2__ *lcs1* *lcs2* *len1* *len2* + + Similar to __lcsInvertMerge__. Instead of directly taking the result of a + call to __longestCommonSubsequence__ this subcommand expects the indices for + the two sequences in two separate lists. + + - __::struct::list__ __reverse__ *sequence* + + The subcommand takes a single *sequence* as argument and returns a new + sequence containing the elements of the input sequence in reverse order. + + - __::struct::list__ __shuffle__ *list* + + The subcommand takes a *list* and returns a copy of that list with the + elements it contains in random order. Every possible ordering of elements is + equally likely to be generated. The Fisher-Yates shuffling algorithm is used + internally. + + - __::struct::list__ __assign__ *sequence* *varname* ?*varname*?... + + The subcommand assigns the first __n__ elements of the input *sequence* to + the one or more variables whose names were listed after the sequence, where + __n__ is the number of specified variables. + + If there are more variables specified than there are elements in the + *sequence* the empty string will be assigned to the superfluous variables. + + If there are more elements in the *sequence* than variable names specified + the subcommand returns a list containing the unassigned elements. Else an + empty list is returned. + + tclsh> ::struct::list assign {a b c d e} foo bar + c d e + tclsh> set foo + a + tclsh> set bar + b + + - __::struct::list__ __flatten__ ?__-full__? ?__--__? *sequence* + + The subcommand takes a single *sequence* and returns a new sequence where + one level of nesting was removed from the input sequence. In other words, + the sublists in the input sequence are replaced by their elements. + + The subcommand will remove any nesting it finds if the option __-full__ is + specified. + + tclsh> ::struct::list flatten {1 2 3 {4 5} {6 7} {{8 9}} 10} + 1 2 3 4 5 6 7 {8 9} 10 + tclsh> ::struct::list flatten -full {1 2 3 {4 5} {6 7} {{8 9}} 10} + 1 2 3 4 5 6 7 8 9 10 + + - __::struct::list__ __map__ *sequence* *cmdprefix* + + The subcommand takes a *sequence* to operate on and a command prefix + (*cmdprefix*) specifying an operation, applies the command prefix to each + element of the sequence and returns a sequence consisting of the results of + that application. + + The command prefix will be evaluated with a single word appended to it. The + evaluation takes place in the context of the caller of the subcommand. + + tclsh> # squaring all elements in a list + + tclsh> proc sqr {x} {expr {$x*$x}} + tclsh> ::struct::list map {1 2 3 4 5} sqr + 1 4 9 16 25 + + tclsh> # Retrieving the second column from a matrix + tclsh> # given as list of lists. + + tclsh> proc projection {n list} {::lindex $list $n} + tclsh> ::struct::list map {{a b c} {1 2 3} {d f g}} {projection 1} + b 2 f + + - __::struct::list__ __mapfor__ *var* *sequence* *script* + + The subcommand takes a *sequence* to operate on and a tcl *script*, applies + the script to each element of the sequence and returns a sequence consisting + of the results of that application. + + The script will be evaluated as is, and has access to the current list + element through the specified iteration variable *var*. The evaluation takes + place in the context of the caller of the subcommand. + + tclsh> # squaring all elements in a list + + tclsh> ::struct::list mapfor x {1 2 3 4 5} { + expr {$x * $x} + } + 1 4 9 16 25 + + tclsh> # Retrieving the second column from a matrix + tclsh> # given as list of lists. + + tclsh> ::struct::list mapfor x {{a b c} {1 2 3} {d f g}} { + lindex $x 1 + } + b 2 f + + - __::struct::list__ __filter__ *sequence* *cmdprefix* + + The subcommand takes a *sequence* to operate on and a command prefix + (*cmdprefix*) specifying an operation, applies the command prefix to each + element of the sequence and returns a sequence consisting of all elements of + the *sequence* for which the command prefix returned __true__. In other + words, this command filters out all elements of the input *sequence* which + fail the test the *cmdprefix* represents, and returns the remaining + elements. + + The command prefix will be evaluated with a single word appended to it. The + evaluation takes place in the context of the caller of the subcommand. + + tclsh> # removing all odd numbers from the input + + tclsh> proc even {x} {expr {($x % 2) == 0}} + tclsh> ::struct::list filter {1 2 3 4 5} even + 2 4 + + *Note:* The __filter__ is a specialized application of __fold__ where the + result is extended with the current item or not, depending o nthe result of + the test. + + - __::struct::list__ __filterfor__ *var* *sequence* *expr* + + The subcommand takes a *sequence* to operate on and a tcl expression + (*expr*) specifying a condition, applies the conditionto each element of the + sequence and returns a sequence consisting of all elements of the *sequence* + for which the expression returned __true__. In other words, this command + filters out all elements of the input *sequence* which fail the test the + condition *expr* represents, and returns the remaining elements. + + The expression will be evaluated as is, and has access to the current list + element through the specified iteration variable *var*. The evaluation takes + place in the context of the caller of the subcommand. + + tclsh> # removing all odd numbers from the input + + tclsh> ::struct::list filterfor x {1 2 3 4 5} {($x % 2) == 0} + 2 4 + + - __::struct::list__ __split__ *sequence* *cmdprefix* ?*passVar* *failVar*? + + This is a variant of method __filter__, see above. Instead of returning just + the elements passing the test we get lists of both passing and failing + elements. + + If no variable names are specified then the result of the command will be a + list containing the list of passing elements, and the list of failing + elements, in this order. Otherwise the lists of passing and failing elements + are stored into the two specified variables, and the result will be a list + containing two numbers, the number of elements passing the test, and the + number of elements failing, in this order. + + The interface to the test is the same as used by __filter__. + + - __::struct::list__ __fold__ *sequence* *initialvalue* *cmdprefix* + + The subcommand takes a *sequence* to operate on, an arbitrary string + *initial value* and a command prefix (*cmdprefix*) specifying an operation. + + The command prefix will be evaluated with two words appended to it. The + second of these words will always be an element of the sequence. The + evaluation takes place in the context of the caller of the subcommand. + + It then reduces the sequence into a single value through repeated + application of the command prefix and returns that value. This reduction is + done by + + * __1__ + + Application of the command to the initial value and the first element of + the list. + + * __2__ + + Application of the command to the result of the last call and the second + element of the list. + + * __...__ + + * __i__ + + Application of the command to the result of the last call and the + __i__'th element of the list. + + * __...__ + + * __end__ + + Application of the command to the result of the last call and the last + element of the list. The result of this call is returned as the result + of the subcommand. + + tclsh> # summing the elements in a list. + tclsh> proc + {a b} {expr {$a + $b}} + tclsh> ::struct::list fold {1 2 3 4 5} 0 + + 15 + + - __::struct::list__ __shift__ *listvar* + + The subcommand takes the list contained in the variable named by *listvar* + and shifts it down one element. After the call *listvar* will contain a list + containing the second to last elements of the input list. The first element + of the ist is returned as the result of the command. Shifting the empty list + does nothing. + + - __::struct::list__ __iota__ *n* + + The subcommand returns a list containing the integer numbers in the range + __[0,n)__. The element at index __i__ of the list contain the number __i__. + + For "*n* == __0__" an empty list will be returned. + + - __::struct::list__ __equal__ *a* *b* + + The subcommand compares the two lists *a* and *b* for equality. In other + words, they have to be of the same length and have to contain the same + elements in the same order. If an element is a list the same definition of + equality applies recursively. + + A boolean value will be returned as the result of the command. This value + will be __true__ if the two lists are equal, and __false__ else. + + - __::struct::list__ __repeat__ *size* *element1* ?*element2* *element3*...? + + The subcommand creates a list of length "*size* * *number of elements*" by + repeating *size* times the sequence of elements *element1* *element2* *...*. + *size* must be a positive integer, *element*__n__ can be any Tcl value. Note + that __repeat 1 arg ...__ is identical to __list arg ...__, though the *arg* + is required with __repeat__. + + *Examples:* + + tclsh> ::struct::list repeat 3 a + a a a + tclsh> ::struct::list repeat 3 [::struct::list repeat 3 0] + {0 0 0} {0 0 0} {0 0 0} + tclsh> ::struct::list repeat 3 a b c + a b c a b c a b c + tclsh> ::struct::list repeat 3 [::struct::list repeat 2 a] b c + {a a} b c {a a} b c {a a} b c + + - __::struct::list__ __repeatn__ *value* *size*... + + The subcommand creates a (nested) list containing the *value* in all + positions. The exact size and degree of nesting is determined by the *size* + arguments, all of which have to be integer numbers greater than or equal to + zero. + + A single argument *size* which is a list of more than one element will be + treated as if more than argument *size* was specified. + + If only one argument *size* is present the returned list will not be nested, + of length *size* and contain *value* in all positions. If more than one + *size* argument is present the returned list will be nested, and of the + length specified by the last *size* argument given to it. The elements of + that list are defined as the result of __Repeat__ for the same arguments, + but with the last *size* value removed. + + An empty list will be returned if no *size* arguments are present. + + tclsh> ::struct::list repeatn 0 3 4 + {0 0 0} {0 0 0} {0 0 0} {0 0 0} + tclsh> ::struct::list repeatn 0 {3 4} + {0 0 0} {0 0 0} {0 0 0} {0 0 0} + tclsh> ::struct::list repeatn 0 {3 4 5} + {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} + + - __::struct::list__ __dbJoin__ ?__-inner__|__-left__|__-right__|__-full__? ?__-keys__ *varname*? {*keycol* *table*}... + + The method performs a table join according to relational algebra. The + execution of any of the possible outer join operation is triggered by the + presence of either option __-left__, __-right__, or __-full__. If none of + these options is present a regular inner join will be performed. This can + also be triggered by specifying __-inner__. The various possible join + operations are explained in detail in section [TABLE JOIN](#section4). + + If the __-keys__ is present its argument is the name of a variable to store + the full list of found keys into. Depending on the exact nature of the input + table and the join mode the output table may not contain all the keys by + default. In such a case the caller can declare a variable for this + information and then insert it into the output table on its own, as she will + have more information about the placement than this command. + + What is left to explain is the format of the arguments. + + The *keycol* arguments are the indices of the columns in the tables which + contain the key values to use for the joining. Each argument applies to the + table following immediately after it. The columns are counted from __0__, + which references the first column. The table associated with the column + index has to have at least *keycol*+1 columns. An error will be thrown if + there are less. + + The *table* arguments represent a table or matrix of rows and columns of + values. We use the same representation as generated and consumed by the + methods __get rect__ and __set rect__ of + __[matrix](../../../../index.md#matrix)__ objects. In other words, each + argument is a list, representing the whole matrix. Its elements are lists + too, each representing a single rows of the matrix. The elements of the + row-lists are the column values. + + The table resulting from the join operation is returned as the result of the + command. We use the same representation as described above for the input + *table*s. + + - __::struct::list__ __dbJoinKeyed__ ?__-inner__|__-left__|__-right__|__-full__? ?__-keys__ *varname*? *table*... + + The operations performed by this method are the same as described above for + __dbJoin__. The only difference is in the specification of the keys to use. + Instead of using column indices separate from the table here the keys are + provided within the table itself. The row elements in each *table* are not + the lists of column values, but a two-element list where the second element + is the regular list of column values and the first element is the key to + use. + + - __::struct::list__ __swap__ *listvar* *i* *j* + + The subcommand exchanges the elements at the indices *i* and *j* in the list + stored in the variable named by *listvar*. The list is modified in place, + and also returned as the result of the subcommand. + + - __::struct::list__ __firstperm__ *list* + + This subcommand returns the lexicographically first permutation of the input + *list*. + + - __::struct::list__ __nextperm__ *perm* + + This subcommand accepts a permutation of a set of elements (provided by + *perm*) and returns the next permutatation in lexicographic sequence. + + The algorithm used here is by Donal E. Knuth, see section + [REFERENCES](#section5) for details. + + - __::struct::list__ __permutations__ *list* + + This subcommand returns a list containing all permutations of the input + *list* in lexicographic order. + + - __::struct::list__ __foreachperm__ *var* *list* *body* + + This subcommand executes the script *body* once for each permutation of the + specified *list*. The permutations are visited in lexicographic order, and + the variable *var* is set to the permutation for which *body* is currently + executed. The result of the loop command is the empty string. + +# LONGEST COMMON SUBSEQUENCE AND FILE COMPARISON + +The __longestCommonSubsequence__ subcommand forms the core of a flexible system +for doing differential comparisons of files, similar to the capability offered +by the Unix command __[diff](../../../../index.md#diff)__. While this procedure +is quite rapid for many tasks of file comparison, its performance degrades +severely if *sequence2* contains many equal elements (as, for instance, when +using this procedure to compare two files, a quarter of whose lines are blank. +This drawback is intrinsic to the algorithm used (see the Reference for +details). + +One approach to dealing with the performance problem that is sometimes effective +in practice is arbitrarily to exclude elements that appear more than a certain +number of times. This number is provided as the *maxOccurs* parameter. If +frequent lines are excluded in this manner, they will not appear in the common +subsequence that is computed; the result will be the longest common subsequence +of infrequent elements. The procedure __longestCommonSubsequence2__ implements +this heuristic. It functions as a wrapper around __longestCommonSubsequence__; +it computes the longest common subsequence of infrequent elements, and then +subdivides the subsequences that lie between the matches to approximate the true +longest common subsequence. + +# TABLE JOIN + +This is an operation from relational algebra for relational databases. + +The easiest way to understand the regular inner join is that it creates the +cartesian product of all the tables involved first and then keeps only all those +rows in the resulting table for which the values in the specified key columns +are equal to each other. + +Implementing this description naively, i.e. as described above will generate a +*huge* intermediate result. To avoid this the cartesian product and the +filtering of row are done at the same time. What is required is a fast way to +determine if a key is present in a table. In a true database this is done +through indices. Here we use arrays internally. + +An *outer* join is an extension of the inner join for two tables. There are +three variants of outerjoins, called *left*, *right*, and *full* outer joins. +Their result always contains all rows from an inner join and then some +additional rows. + + 1. For the left outer join the additional rows are all rows from the left + table for which there is no key in the right table. They are joined to an + empty row of the right table to fit them into the result. + + 1. For the right outer join the additional rows are all rows from the right + table for which there is no key in the left table. They are joined to an + empty row of the left table to fit them into the result. + + 1. The full outer join combines both left and right outer join. In other + words, the additional rows are as defined for left outer join, and right + outer join, combined. + +We extend all the joins from two to __n__ tables (__n__ > 2) by executing + + (...((table1 join table2) join table3) ...) join tableN + +Examples for all the joins: + + Inner Join + + {0 foo} {0 bagel} {0 foo 0 bagel} + {1 snarf} inner join {1 snatz} = {1 snarf 1 snatz} + {2 blue} {3 driver} + + Left Outer Join + + {0 foo} {0 bagel} {0 foo 0 bagel} + {1 snarf} left outer join {1 snatz} = {1 snarf 1 snatz} + {2 blue} {3 driver} {2 blue {} {}} + + Right Outer Join + + {0 foo} {0 bagel} {0 foo 0 bagel} + {1 snarf} right outer join {1 snatz} = {1 snarf 1 snatz} + {2 blue} {3 driver} {{} {} 3 driver} + + Full Outer Join + + {0 foo} {0 bagel} {0 foo 0 bagel} + {1 snarf} full outer join {1 snatz} = {1 snarf 1 snatz} + {2 blue} {3 driver} {2 blue {} {}} + {{} {} 3 driver} + +# REFERENCES + + 1. J. W. Hunt and M. D. McIlroy, "An algorithm for differential file + comparison," Comp. Sci. Tech. Rep. #41, Bell Telephone Laboratories (1976). + Available on the Web at the second author's personal site: + [http://www.cs.dartmouth.edu/~doug/](http://www.cs.dartmouth.edu/~doug/) + + 1. Donald E. Knuth, "Fascicle 2b of 'The Art of Computer Programming' volume + 4". Available on the Web at the author's personal site: + [http://www-cs-faculty.stanford.edu/~knuth/fasc2b.ps.gz](http://www-cs-faculty.stanford.edu/~knuth/fasc2b.ps.gz). + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: list* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Fisher-Yates](../../../../index.md#fisher_yates), +[assign](../../../../index.md#assign), [common](../../../../index.md#common), +[comparison](../../../../index.md#comparison), +[diff](../../../../index.md#diff), +[differential](../../../../index.md#differential), +[equal](../../../../index.md#equal), [equality](../../../../index.md#equality), +[filter](../../../../index.md#filter), [first +permutation](../../../../index.md#first_permutation), +[flatten](../../../../index.md#flatten), +[folding](../../../../index.md#folding), [full outer +join](../../../../index.md#full_outer_join), [generate +permutations](../../../../index.md#generate_permutations), [inner +join](../../../../index.md#inner_join), [join](../../../../index.md#join), [left +outer join](../../../../index.md#left_outer_join), +[list](../../../../index.md#list), [longest common +subsequence](../../../../index.md#longest_common_subsequence), +[map](../../../../index.md#map), [next +permutation](../../../../index.md#next_permutation), [outer +join](../../../../index.md#outer_join), +[permutation](../../../../index.md#permutation), +[reduce](../../../../index.md#reduce), +[repeating](../../../../index.md#repeating), +[repetition](../../../../index.md#repetition), +[reshuffle](../../../../index.md#reshuffle), +[reverse](../../../../index.md#reverse), [right outer +join](../../../../index.md#right_outer_join), +[shuffle](../../../../index.md#shuffle), +[subsequence](../../../../index.md#subsequence), +[swapping](../../../../index.md#swapping) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2003-2005 by Kevin B. Kenny. All rights reserved +Copyright © 2003-2012 Andreas Kupries ADDED embedded/md/tcllib/files/modules/struct/struct_set.md Index: embedded/md/tcllib/files/modules/struct/struct_set.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/struct_set.md @@ -0,0 +1,177 @@ + +[//000000001]: # (struct::set - Tcl Data Structures) +[//000000002]: # (Generated from file 'struct_set.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::set(n) 2.2.3 tcllib "Tcl Data Structures") + +# NAME + +struct::set - Procedures for manipulating sets + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [REFERENCES](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.0 +package require struct::set ?2.2.3? + +[__::struct::set__ __empty__ *set*](#1) +[__::struct::set__ __size__ *set*](#2) +[__::struct::set__ __contains__ *set* *item*](#3) +[__::struct::set__ __union__ ?*set1*...?](#4) +[__::struct::set__ __intersect__ ?*set1*...?](#5) +[__::struct::set__ __difference__ *set1* *set2*](#6) +[__::struct::set__ __symdiff__ *set1* *set2*](#7) +[__::struct::set__ __intersect3__ *set1* *set2*](#8) +[__::struct::set__ __equal__ *set1* *set2*](#9) +[__::struct::set__ __include__ *svar* *item*](#10) +[__::struct::set__ __exclude__ *svar* *item*](#11) +[__::struct::set__ __add__ *svar* *set*](#12) +[__::struct::set__ __subtract__ *svar* *set*](#13) +[__::struct::set__ __subsetof__ *A* *B*](#14) + +# DESCRIPTION + +The __::struct::set__ namespace contains several useful commands for processing +finite sets. + +It exports only a single command, __struct::set__. All functionality provided +here can be reached through a subcommand of this command. + +*Note:* As of version 2.2 of this package a critcl based C implementation is +available. This implementation however requires Tcl 8.4 to run. + +# COMMANDS + + - __::struct::set__ __empty__ *set* + + Returns a boolean value indicating if the *set* is empty (__true__), or not + (__false__). + + - __::struct::set__ __size__ *set* + + Returns an integer number greater than or equal to zero. This is the number + of elements in the *set*. In other words, its cardinality. + + - __::struct::set__ __contains__ *set* *item* + + Returns a boolean value indicating if the *set* contains the element *item* + (__true__), or not (__false__). + + - __::struct::set__ __union__ ?*set1*...? + + Computes the set containing the union of *set1*, *set2*, etc., i.e. "*set1* + + *set2* + ...", and returns this set as the result of the command. + + - __::struct::set__ __intersect__ ?*set1*...? + + Computes the set containing the intersection of *set1*, *set2*, etc., i.e. + "*set1* * *set2* * ...", and returns this set as the result of the command. + + - __::struct::set__ __difference__ *set1* *set2* + + Computes the set containing the difference of *set1* and *set2*, i.e. + ("*set1* - *set2*") and returns this set as the result of the command. + + - __::struct::set__ __symdiff__ *set1* *set2* + + Computes the set containing the symmetric difference of *set1* and *set2*, + i.e. ("(*set1* - *set2*) + (*set2* - *set1*)") and returns this set as the + result of the command. + + - __::struct::set__ __intersect3__ *set1* *set2* + + This command is a combination of the methods __intersect__ and + __difference__. It returns a three-element list containing "*set1***set2*", + "*set1*-*set2*", and "*set2*-*set1*", in this order. In other words, the + intersection of the two parameter sets, and their differences. + + - __::struct::set__ __equal__ *set1* *set2* + + Returns a boolean value indicating if the two sets are equal (__true__) or + not (__false__). + + - __::struct::set__ __include__ *svar* *item* + + The element *item* is added to the set specified by the variable name in + *svar*. The return value of the command is empty. This is the equivalent of + __lappend__ for sets. If the variable named by *svar* does not exist it will + be created. + + - __::struct::set__ __exclude__ *svar* *item* + + The element *item* is removed from the set specified by the variable name in + *svar*. The return value of the command is empty. This is a near-equivalent + of __lreplace__ for sets. + + - __::struct::set__ __add__ *svar* *set* + + All the element of *set* are added to the set specified by the variable name + in *svar*. The return value of the command is empty. This is like the method + __include__, but for the addition of a whole set. If the variable named by + *svar* does not exist it will be created. + + - __::struct::set__ __subtract__ *svar* *set* + + All the element of *set* are removed from the set specified by the variable + name in *svar*. The return value of the command is empty. This is like the + method __exclude__, but for the removal of a whole set. + + - __::struct::set__ __subsetof__ *A* *B* + + Returns a boolean value indicating if the set *A* is a true subset of or + equal to the set *B* (__true__), or not (__false__). + +# REFERENCES + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: set* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[cardinality](../../../../index.md#cardinality), +[difference](../../../../index.md#difference), +[emptiness](../../../../index.md#emptiness), +[exclusion](../../../../index.md#exclusion), +[inclusion](../../../../index.md#inclusion), +[intersection](../../../../index.md#intersection), +[membership](../../../../index.md#membership), [set](../../../../index.md#set), +[symmetric difference](../../../../index.md#symmetric_difference), +[union](../../../../index.md#union) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2004-2008 Andreas Kupries ADDED embedded/md/tcllib/files/modules/struct/struct_tree.md Index: embedded/md/tcllib/files/modules/struct/struct_tree.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/struct_tree.md @@ -0,0 +1,692 @@ + +[//000000001]: # (struct::tree - Tcl Data Structures) +[//000000002]: # (Generated from file 'struct_tree.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::tree(n) 2.1.1 tcllib "Tcl Data Structures") + +# NAME + +struct::tree - Create and manipulate tree objects + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Tree CLASS API](#subsection1) + + - [Tree OBJECT API](#subsection2) + + - [Changes for 2.0](#subsection3) + + - [EXAMPLES](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require struct::tree ?2.1.1? +package require struct::list ?1.5? + +[__::struct::tree__ ?*treeName*? ?__=__|__:=__|__as__|__deserialize__ *source*?](#1) +[__treeName__ __option__ ?*arg arg ...*?](#2) +[__::struct::tree::prune__](#3) +[*treeName* __=__ *sourcetree*](#4) +[*treeName* __-->__ *desttree*](#5) +[*treeName* __ancestors__ *node*](#6) +[*treeName* __append__ *node* *key* *value*](#7) +[*treeName* __attr__ *key*](#8) +[*treeName* __attr__ *key* __-nodes__ *list*](#9) +[*treeName* __attr__ *key* __-glob__ *globpattern*](#10) +[*treeName* __attr__ *key* __-regexp__ *repattern*](#11) +[*treeName* __children__ ?__-all__? *node* ?__filter__ *cmdprefix*?](#12) +[*treeName* __cut__ *node*](#13) +[*treeName* __delete__ *node* ?*node* ...?](#14) +[*treeName* __depth__ *node*](#15) +[*treeName* __descendants__ *node* ?__filter__ *cmdprefix*?](#16) +[*treeName* __deserialize__ *serialization*](#17) +[*treeName* __destroy__](#18) +[*treeName* __exists__ *node*](#19) +[*treeName* __get__ *node* *key*](#20) +[*treeName* __getall__ *node* ?*pattern*?](#21) +[*treeName* __keys__ *node* ?*pattern*?](#22) +[*treeName* __keyexists__ *node* *key*](#23) +[*treeName* __index__ *node*](#24) +[*treeName* __insert__ *parent* *index* ?*child* ?*child* ...??](#25) +[*treeName* __isleaf__ *node*](#26) +[*treeName* __lappend__ *node* *key* *value*](#27) +[*treeName* __leaves__](#28) +[*treeName* __move__ *parent* *index* *node* ?*node* ...?](#29) +[*treeName* __next__ *node*](#30) +[*treeName* __numchildren__ *node*](#31) +[*treeName* __nodes__](#32) +[*treeName* __parent__ *node*](#33) +[*treeName* __previous__ *node*](#34) +[*treeName* __rename__ *node* *newname*](#35) +[*treeName* __rootname__](#36) +[*treeName* __serialize__ ?*node*?](#37) +[*treeName* __set__ *node* *key* ?*value*?](#38) +[*treeName* __size__ ?*node*?](#39) +[*treeName* __splice__ *parent* *from* ?*to*? ?*child*?](#40) +[*treeName* __swap__ *node1* *node2*](#41) +[*treeName* __unset__ *node* *key*](#42) +[*treeName* __walk__ *node* ?__-order__ *order*? ?__-type__ *type*? *loopvar* *script*](#43) +[*treeName* __walkproc__ *node* ?__-order__ *order*? ?__-type__ *type*? *cmdprefix*](#44) + +# DESCRIPTION + +A tree is a collection of named elements, called nodes, one of which is +distinguished as a root, along with a relation ("parenthood") that places a +hierarchical structure on the nodes. (Data Structures and Algorithms; Aho, +Hopcroft and Ullman; Addison-Wesley, 1987). In addition to maintaining the node +relationships, this tree implementation allows any number of keyed values to be +associated with each node. + +The element names can be arbitrary strings. + +A tree is thus similar to an array, but with three important differences: + + 1. Trees are accessed through an object command, whereas arrays are accessed + as variables. (This means trees cannot be local to a procedure.) + + 1. Trees have a hierarchical structure, whereas an array is just an unordered + collection. + + 1. Each node of a tree has a separate collection of attributes and values. + This is like an array where every value is a dictionary. + +*Note:* The major version of the package +__[struct](../../../../index.md#struct)__ has been changed to version 2.0, due +to backward incompatible changes in the API of this module. Please read the +section [Changes for 2.0](#subsection3) for a full list of all changes, +incompatible and otherwise. + +# API + +## Tree CLASS API + +The main commands of the package are: + + - __::struct::tree__ ?*treeName*? ?__=__|__:=__|__as__|__deserialize__ *source*? + + The command creates a new tree object with an associated global Tcl command + whose name is *treeName*. This command may be used to invoke various + operations on the tree. It has the following general form: + + * __treeName__ __option__ ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. + + If *treeName* is not specified a unique name will be generated by the + package itself. If a *source* is specified the new tree will be initialized + to it. For the operators __=__, __:=__, and __as__ *source* is interpreted + as the name of another tree object, and the assignment operator __=__ will + be executed. For __deserialize__ the *source* is a serialized tree object + and __deserialize__ will be executed. + + In other words + + ::struct::tree mytree = b + + is equivalent to + + ::struct::tree mytree + mytree = b + + and + + ::struct::tree mytree deserialize $b + + is equivalent to + + ::struct::tree mytree + mytree deserialize $b + + - __::struct::tree::prune__ + + This command is provided outside of the tree methods, as it is not a tree + method per se. It however interacts tightly with the method __walk__. When + used in the walk script it causes the traversal to ignore the children of + the node we are currently at. This command cannot be used with the traversal + modes which look at children before their parent, i.e. __post__ and __in__. + The only applicable orders of traversal are __pre__ and __both__. An error + is thrown if the command and chosen order of traversal do not fit. + +## Tree OBJECT API + +Two general observations beforehand: + + 1. The root node of the tree can be used in most places where a node is asked + for. The default name of the rootnode is "root", but this can be changed + with the method __rename__ (see below). Whatever the current name for the + root node of the tree is, it can be retrieved by calling the method + __rootname__. + + 1. The method __insert__ is the only way to create new nodes, and they are + automatically added to a parent. A tree object cannot have nodes without a + parent, save the root node. + +And now the methods supported by tree objects created by this package: + + - *treeName* __=__ *sourcetree* + + This is the assignment operator for tree objects. It copies the tree + contained in the tree object *sourcetree* over the tree data in *treeName*. + The old contents of *treeName* are deleted by this operation. + + This operation is in effect equivalent to + + *treeName* __deserialize__ [*sourcetree* __serialize__] + + - *treeName* __-->__ *desttree* + + This is the reverse assignment operator for tree objects. It copies the tree + contained in the tree object *treeName* over the tree data in the object + *desttree*. The old contents of *desttree* are deleted by this operation. + + This operation is in effect equivalent to + + *desttree* __deserialize__ [*treeName* __serialize__] + + - *treeName* __ancestors__ *node* + + This method extends the method __parent__ and returns a list containing all + ancestor nodes to the specified *node*. The immediate ancestor, in other + words, parent node, is the first element in that list, its parent the second + element, and so on until the root node is reached, making it the last + element of the returned list. + + - *treeName* __append__ *node* *key* *value* + + Appends a *value* to one of the keyed values associated with an node. + Returns the new value given to the attribute *key*. + + - *treeName* __attr__ *key* + + - *treeName* __attr__ *key* __-nodes__ *list* + + - *treeName* __attr__ *key* __-glob__ *globpattern* + + - *treeName* __attr__ *key* __-regexp__ *repattern* + + This method retrieves the value of the attribute named *key*, for all nodes + in the tree (matching the restriction specified via one of the possible + options) and having the specified attribute. + + The result is a dictionary mapping from node names to the value of attribute + *key* at that node. Nodes not having the attribute *key*, or not passing a + specified restriction, are not listed in the result. + + The possible restrictions are: + + * __-nodes__ + + The value is a list of nodes. Only the nodes mentioned in this list are + searched for the attribute. + + * __-glob__ + + The value is a glob pattern. Only the nodes in the tree whose names + match this pattern are searched for the attribute. + + * __-regexp__ + + The value is a regular expression. Only the nodes in the tree whose + names match this pattern are searched for the attribute. + + - *treeName* __children__ ?__-all__? *node* ?__filter__ *cmdprefix*? + + Return a list of the children of *node*. If the option __-all__ is + specified, then not only the direct children, but their children, and so on + are returned in the result. If a filter command is specified only those + nodes are listed in the final result which pass the test. The command in + *cmdprefix* is called with two arguments, the name of the tree object, and + the name of the node in question. It is executed in the context of the + caller and has to return a boolean value. Nodes for which the command + returns __false__ are removed from the result list before it is returned to + the caller. + + Some examples: + + mytree insert root end 0 ; mytree set 0 volume 30 + mytree insert root end 1 + mytree insert root end 2 + mytree insert 0 end 3 + mytree insert 0 end 4 + mytree insert 4 end 5 ; mytree set 5 volume 50 + mytree insert 4 end 6 + + proc vol {t n} { + $t keyexists $n volume + } + proc vgt40 {t n} { + if {![$t keyexists $n volume]} {return 0} + expr {[$t get $n volume] > 40} + } + + tclsh> lsort [mytree children -all root filter vol] + 0 5 + + tclsh> lsort [mytree children -all root filter vgt40] + 5 + + tclsh> lsort [mytree children root filter vol] + 0 + + tclsh> puts ([lsort [mytree children root filter vgt40]]) + () + + - *treeName* __cut__ *node* + + Removes the node specified by *node* from the tree, but not its children. + The children of *node* are made children of the parent of the *node*, at the + index at which *node* was located. + + - *treeName* __delete__ *node* ?*node* ...? + + Removes the specified nodes from the tree. All of the nodes' children will + be removed as well to prevent orphaned nodes. + + - *treeName* __depth__ *node* + + Return the number of steps from node *node* to the root node. + + - *treeName* __descendants__ *node* ?__filter__ *cmdprefix*? + + This method extends the method __children__ and returns a list containing + all nodes descending from *node*, and passing the filter, if such was + specified. + + This is actually the same as "*treeName* __children__ __-all__". + __descendants__ should be prefered, and "children -all" will be deprecated + sometime in the future. + + - *treeName* __deserialize__ *serialization* + + This is the complement to __serialize__. It replaces tree data in *treeName* + with the tree described by the *serialization* value. The old contents of + *treeName* are deleted by this operation. + + - *treeName* __destroy__ + + Destroy the tree, including its storage space and associated command. + + - *treeName* __exists__ *node* + + Returns true if the specified node exists in the tree. + + - *treeName* __get__ *node* *key* + + Returns the value associated with the key *key* for the node *node*. + + - *treeName* __getall__ *node* ?*pattern*? + + Returns a dictionary (suitable for use with [__array set__]) containing the + attribute data for the *node*. If the glob *pattern* is specified only the + attributes whose names match the pattern will be part of the dictionary. + + - *treeName* __keys__ *node* ?*pattern*? + + Returns a list of keys for the *node*. If the *pattern* is specified only + the attributes whose names match the pattern will be part of the returned + list. The pattern is a __glob__ pattern. + + - *treeName* __keyexists__ *node* *key* + + Return true if the specified *key* exists for the *node*. + + - *treeName* __index__ *node* + + Returns the index of *node* in its parent's list of children. For example, + if a node has *nodeFoo*, *nodeBar*, and *nodeBaz* as children, in that + order, the index of *nodeBar* is 1. + + - *treeName* __insert__ *parent* *index* ?*child* ?*child* ...?? + + Insert one or more nodes into the tree as children of the node *parent*. The + nodes will be added in the order they are given. If *parent* is __root__, it + refers to the root of the tree. The new nodes will be added to the *parent* + node's child list at the index given by *index*. The *index* can be __end__ + in which case the new nodes will be added after the current last child. + Indices of the form "end-__n__" are accepted as well. + + If any of the specified children already exist in *treeName*, those nodes + will be moved from their original location to the new location indicated by + this command. + + If no *child* is specified, a single node will be added, and a name will be + generated for the new node. The generated name is of the form *node*__x__, + where __x__ is a number. If names are specified they must neither contain + whitespace nor colons (":"). + + The return result from this command is a list of nodes added. + + - *treeName* __isleaf__ *node* + + Returns true if *node* is a leaf of the tree (if *node* has no children), + false otherwise. + + - *treeName* __lappend__ *node* *key* *value* + + Appends a *value* (as a list) to one of the keyed values associated with an + *node*. Returns the new value given to the attribute *key*. + + - *treeName* __leaves__ + + Return a list containing all leaf nodes known to the tree. + + - *treeName* __move__ *parent* *index* *node* ?*node* ...? + + Make the specified nodes children of *parent*, inserting them into the + parent's child list at the index given by *index*. Note that the command + will take all nodes out of the tree before inserting them under the new + parent, and that it determines the position to place them into after the + removal, before the re-insertion. This behaviour is important when it comes + to moving one or more nodes to a different index without changing their + parent node. + + - *treeName* __next__ *node* + + Return the right sibling of *node*, or the empty string if *node* was the + last child of its parent. + + - *treeName* __numchildren__ *node* + + Return the number of immediate children of *node*. + + - *treeName* __nodes__ + + Return a list containing all nodes known to the tree. + + - *treeName* __parent__ *node* + + Return the parent of *node*. + + - *treeName* __previous__ *node* + + Return the left sibling of *node*, or the empty string if *node* was the + first child of its parent. + + - *treeName* __rename__ *node* *newname* + + Renames the node *node* to *newname*. An error is thrown if either the node + does not exist, or a node with name *newname* does exist. The result of the + command is the new name of the node. + + - *treeName* __rootname__ + + Returns the name of the root node of the tree. + + - *treeName* __serialize__ ?*node*? + + This method serializes the sub-tree starting at *node*. In other words it + returns a tcl *value* completely describing the tree starting at *node*. + This allows, for example, the transfer of tree objects (or parts thereof) + over arbitrary channels, persistence, etc. This method is also the basis for + both the copy constructor and the assignment operator. + + The result of this method has to be semantically identical over all + implementations of the tree interface. This is what will enable us to copy + tree data between different implementations of the same interface. + + The result is a list containing containing a multiple of three elements. It + is like a serialized array except that there are two values following each + key. They are the names of the nodes in the serialized tree. The two values + are a reference to the parent node and the attribute data, in this order. + + The reference to the parent node is the empty string for the root node of + the tree. For all other nodes it is the index of the parent node in the + list. This means that they are integers, greater than or equal to zero, less + than the length of the list, and multiples of three. The order of the nodes + in the list is important insofar as it is used to reconstruct the lists of + children for each node. The children of a node have to be listed in the + serialization in the same order as they are listed in their parent in the + tree. + + The attribute data of a node is a dictionary, i.e. a list of even length + containing a serialized array. For a node without attribute data the + dictionary is the empty list. + + *Note:* While the current implementation returns the root node as the first + element of the list, followed by its children and their children in a + depth-first traversal this is not necessarily true for other + implementations. The only information a reader of the serialized data can + rely on for the structure of the tree is that the root node is signaled by + the empty string for the parent reference, that all other nodes refer to + their parent through the index in the list, and that children occur in the + same order as in their parent. + + A possible serialization for the tree structure + + +- d + +- a -+ + root -+- b +- e + +- c + is + + {root {} {} a 0 {} d 3 {} e 3 {} b 0 {} c 0 {}} + + The above assumes that none of the nodes have attributes. + + - *treeName* __set__ *node* *key* ?*value*? + + Set or get one of the keyed values associated with a node. A node may have + any number of keyed values associated with it. If *value* is not specified, + this command returns the current value assigned to the key; if *value* is + specified, this command assigns that value to the key, and returns it. + + - *treeName* __size__ ?*node*? + + Return a count of the number of descendants of the node *node*; if no node + is specified, __root__ is assumed. + + - *treeName* __splice__ *parent* *from* ?*to*? ?*child*? + + Insert a node named *child* into the tree as a child of the node *parent*. + If *parent* is __root__, it refers to the root of the tree. The new node + will be added to the parent node's child list at the index given by *from*. + The children of *parent* which are in the range of the indices *from* and + *to* are made children of *child*. If the value of *to* is not specified it + defaults to __end__. If no name is given for *child*, a name will be + generated for the new node. The generated name is of the form *node*__x__, + where __x__ is a number. The return result from this command is the name of + the new node. + + The arguments *from* and *to* are regular list indices, i.e. the form + "end-__n__" is accepted as well. + + - *treeName* __swap__ *node1* *node2* + + Swap the position of *node1* and *node2* in the tree. + + - *treeName* __unset__ *node* *key* + + Removes a keyed value from the node *node*. The method will do nothing if + the *key* does not exist. + + - *treeName* __walk__ *node* ?__-order__ *order*? ?__-type__ *type*? *loopvar* *script* + + Perform a breadth-first or depth-first walk of the tree starting at the node + *node*. The type of walk, breadth-first or depth-first, is determined by the + value of *type*; __bfs__ indicates breadth-first, __dfs__ indicates + depth-first. Depth-first is the default. The order of the walk, pre-, post-, + both- or in-order is determined by the value of *order*; __pre__ indicates + pre-order, __post__ indicates post-order, __both__ indicates both-order and + __in__ indicates in-order. Pre-order is the default. + + Pre-order walking means that a parent node is visited before any of its + children. For example, a breadth-first search starting from the root will + visit the root, followed by all of the root's children, followed by all of + the root's grandchildren. Post-order walking means that a parent node is + visited after any of its children. Both-order walking means that a parent + node is visited before *and* after any of its children. In-order walking + means that a parent node is visited after its first child and before the + second. This is a generalization of in-order walking for binary trees and + will do the right thing if a binary tree is walked. The combination of a + breadth-first walk with in-order is illegal. + + As the walk progresses, the *script* will be evaluated at each node. The + evaluation takes place in the context of the caller of the method. Regarding + loop variables, these are listed in *loopvar*. If one only one variable is + specified it will be set to the id of the node. When two variables are + specified, i.e. *loopvar* is a true list, then the first variable will be + set to the action performed at the node, and the other to the id of the node + itself. All loop variables are created in the context of the caller. + + There are three possible actions: __enter__, __leave__, or __visit__. + __enter__ actions occur during pre-order walks; __leave__ actions occur + during post-order walks; __visit__ actions occur during in-order walks. In a + both-order walk, the command will be evaluated twice for each node; the + action is __enter__ for the first evaluation, and __leave__ for the second. + + *Note*: The __enter__ action for a node is always performed before the + walker will look at the children of that node. This means that changes made + by the *script* to the children of the node will immediately influence the + walker and the steps it will take. + + Any other manipulation, for example of nodes higher in the tree (i.e already + visited), or upon leaving will have undefined results. They may succeed, + error out, silently compute the wrong result, or anything in between. + + At last a small table showing the relationship between the various options + and the possible actions. + + order type actions notes + ----- ---- ----- ----- + pre dfs enter parent before children + post dfs leave parent after children + in dfs visit parent between first and second child. + both dfs enter, leave parent before and after children + ----- ---- ----- ----- + pre bfs enter parent before children + post bfs leave parent after children + in bfs -- illegal -- + both bfs enter, leave parent before and after children + ----- ---- ----- ----- + + Note the command __::struct::tree::prune__. This command can be used in the + walk script to force the command to ignore the children of the node we are + currently at. It will throw an error if the order of traversal is either + __post__ or __in__ as these modes visit the children before their parent, + making pruning non-sensical. + + - *treeName* __walkproc__ *node* ?__-order__ *order*? ?__-type__ *type*? *cmdprefix* + + This method is like method __walk__ in all essentials, except the interface + to the user code. This method invokes a command prefix with three additional + arguments (tree, node, and action), instead of evaluating a script and + passing the node via a loop variable. + +## Changes for 2.0 + +The following noteworthy changes have occurred: + + 1. The API for accessing attributes and their values has been simplified. + + All functionality regarding the default attribute "data" has been removed. + This default attribute does not exist anymore. All accesses to attributes + have to specify the name of the attribute in question. This backward + *incompatible* change allowed us to simplify the signature of all methods + handling attributes. + + Especially the flag __-key__ is not required anymore, even more, its use is + now forbidden. Please read the documentation for the methods __set__, + __get__, __getall__, __unset__, __append__, __lappend__, __keyexists__ and + __keys__ for a description of the new API's. + + 1. The methods __keys__ and __getall__ now take an optional pattern argument + and will return only attribute data for keys matching this pattern. + + 1. Nodes can now be renamed. See the documentation for the method __rename__. + + 1. The structure has been extended with API's for the serialization and + deserialization of tree objects, and a number of operations based on them + (tree assignment, copy construction). + + Please read the documentation for the methods __serialize__, + __deserialize__, __=__, and __-->__, and the documentation on the + construction of tree objects. + + Beyond the copying of whole tree objects these new API's also enable the + transfer of tree objects over arbitrary channels and for easy persistence. + + 1. The walker API has been streamlined and made more similar to the command + __[foreach](../../../../index.md#foreach)__. In detail: + + - The superfluous option __-command__ has been removed. + + - Ditto for the place holders. Instead of the placeholders two loop + variables have to be specified to contain node and action information. + + - The old command argument has been documented as a script now, which it + was in the past too. + + - The fact that __enter__ actions are called before the walker looks at + the children of a node has been documented now. In other words it is + now officially allowed to manipulate the list of children for a node + under *these* circumstances. It has been made clear that changes under + any other circumstances will have undefined results, from silently + computing the wrong result to erroring out. + + 1. A new method, __attr__, was added allowing the query and retrieval of + attribute data without regard to the node relationship. + + 1. The method __children__ has been extended with the ability to select from + the children of the node based on an arbitrary filtering criterium. Another + extension is the ability to look not only at the immediate children of the + node, but the whole tree below it. + +# EXAMPLES + +The following example demonstrates the creation of new nodes: + + mytree insert root end 0 ; # Create node 0, as child of the root + mytree insert root end 1 2 ; # Ditto nodes 1 & 2 + mytree insert 0 end 3 ; # Now create node 3 as child of node 0 + mytree insert 0 end ; # Create another child of 0, with a + # generated name. The name is returned + # as the result of the command. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: tree* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[breadth-first](../../../../index.md#breadth_first), +[depth-first](../../../../index.md#depth_first), +[in-order](../../../../index.md#in_order), [node](../../../../index.md#node), +[post-order](../../../../index.md#post_order), +[pre-order](../../../../index.md#pre_order), +[serialization](../../../../index.md#serialization), +[tree](../../../../index.md#tree) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2002-2004,2012 Andreas Kupries ADDED embedded/md/tcllib/files/modules/struct/struct_tree1.md Index: embedded/md/tcllib/files/modules/struct/struct_tree1.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/struct/struct_tree1.md @@ -0,0 +1,312 @@ + +[//000000001]: # (struct::tree_v1 - Tcl Data Structures) +[//000000002]: # (Generated from file 'struct_tree1.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (struct::tree_v1(n) 1.2.2 tcllib "Tcl Data Structures") + +# NAME + +struct::tree_v1 - Create and manipulate tree objects + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require struct::tree ?1.2.2? + +[__treeName__ __option__ ?*arg arg ...*?](#1) +[*treeName* __append__ *node* ?-key *key*? *value*](#2) +[*treeName* __children__ *node*](#3) +[*treeName* __cut__ *node*](#4) +[*treeName* __delete__ *node* ?*node* ...?](#5) +[*treeName* __depth__ *node*](#6) +[*treeName* __destroy__](#7) +[*treeName* __exists__ *node*](#8) +[*treeName* __get__ *node* ?__-key__ *key*?](#9) +[*treeName* __getall__ *node*](#10) +[*treeName* __keys__ *node*](#11) +[*treeName* __keyexists__ *node* ?-key *key*?](#12) +[*treeName* __index__ *node*](#13) +[*treeName* __insert__ *parent* *index* ?*child* ?*child* ...??](#14) +[*treeName* __isleaf__ *node*](#15) +[*treeName* __lappend__ *node* ?-key *key*? *value*](#16) +[*treeName* __move__ *parent* *index* *node* ?*node* ...?](#17) +[*treeName* __next__ *node*](#18) +[*treeName* __numchildren__ *node*](#19) +[*treeName* __parent__ *node*](#20) +[*treeName* __previous__ *node*](#21) +[*treeName* __set__ *node* ?__-key__ *key*? ?*value*?](#22) +[*treeName* __size__ ?*node*?](#23) +[*treeName* __splice__ *parent* *from* ?*to*? ?*child*?](#24) +[*treeName* __swap__ *node1* *node2*](#25) +[*treeName* __unset__ *node* ?__-key__ *key*?](#26) +[*treeName* __walk__ *node* ?__-order__ *order*? ?__-type__ *type*? __-command__ *cmd*](#27) + +# DESCRIPTION + +The __::struct::tree__ command creates a new tree object with an associated +global Tcl command whose name is *treeName*. This command may be used to invoke +various operations on the tree. It has the following general form: + + - __treeName__ __option__ ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. + +A tree is a collection of named elements, called nodes, one of which is +distinguished as a root, along with a relation ("parenthood") that places a +hierarchical structure on the nodes. (Data Structures and Algorithms; Aho, +Hopcroft and Ullman; Addison-Wesley, 1987). In addition to maintaining the node +relationships, this tree implementation allows any number of keyed values to be +associated with each node. + +The element names can be arbitrary strings. + +A tree is thus similar to an array, but with three important differences: + + 1. Trees are accessed through an object command, whereas arrays are accessed + as variables. (This means trees cannot be local to a procedure.) + + 1. Trees have a hierarchical structure, whereas an array is just an unordered + collection. + + 1. Each node of a tree has a separate collection of attributes and values. + This is like an array where every value is a dictionary. + +The following commands are possible for tree objects: + + - *treeName* __append__ *node* ?-key *key*? *value* + + Appends a *value* to one of the keyed values associated with an node. If no + *key* is specified, the key __data__ is assumed. + + - *treeName* __children__ *node* + + Return a list of the children of *node*. + + - *treeName* __cut__ *node* + + Removes the node specified by *node* from the tree, but not its children. + The children of *node* are made children of the parent of the *node*, at the + index at which *node* was located. + + - *treeName* __delete__ *node* ?*node* ...? + + Removes the specified nodes from the tree. All of the nodes' children will + be removed as well to prevent orphaned nodes. + + - *treeName* __depth__ *node* + + Return the number of steps from node *node* to the root node. + + - *treeName* __destroy__ + + Destroy the tree, including its storage space and associated command. + + - *treeName* __exists__ *node* + + Returns true if the specified node exists in the tree. + + - *treeName* __get__ *node* ?__-key__ *key*? + + Return the value associated with the key *key* for the node *node*. If no + key is specified, the key __data__ is assumed. + + - *treeName* __getall__ *node* + + Returns a serialized list of key/value pairs (suitable for use with [__array + set__]) for the *node*. + + - *treeName* __keys__ *node* + + Returns a list of keys for the *node*. + + - *treeName* __keyexists__ *node* ?-key *key*? + + Return true if the specified *key* exists for the *node*. If no *key* is + specified, the key __data__ is assumed. + + - *treeName* __index__ *node* + + Returns the index of *node* in its parent's list of children. For example, + if a node has *nodeFoo*, *nodeBar*, and *nodeBaz* as children, in that + order, the index of *nodeBar* is 1. + + - *treeName* __insert__ *parent* *index* ?*child* ?*child* ...?? + + Insert one or more nodes into the tree as children of the node *parent*. The + nodes will be added in the order they are given. If *parent* is __root__, it + refers to the root of the tree. The new nodes will be added to the *parent* + node's child list at the index given by *index*. The *index* can be __end__ + in which case the new nodes will be added after the current last child. + + If any of the specified children already exist in *treeName*, those nodes + will be moved from their original location to the new location indicated by + this command. + + If no *child* is specified, a single node will be added, and a name will be + generated for the new node. The generated name is of the form *node*__x__, + where __x__ is a number. If names are specified they must neither contain + whitespace nor colons (":"). + + The return result from this command is a list of nodes added. + + - *treeName* __isleaf__ *node* + + Returns true if *node* is a leaf of the tree (if *node* has no children), + false otherwise. + + - *treeName* __lappend__ *node* ?-key *key*? *value* + + Appends a *value* (as a list) to one of the keyed values associated with an + *node*. If no *key* is specified, the key __data__ is assumed. + + - *treeName* __move__ *parent* *index* *node* ?*node* ...? + + Make the specified nodes children of *parent*, inserting them into the + parent's child list at the index given by *index*. Note that the command + will take all nodes out of the tree before inserting them under the new + parent, and that it determines the position to place them into after the + removal, before the re-insertion. This behaviour is important when it comes + to moving one or more nodes to a different index without changing their + parent node. + + - *treeName* __next__ *node* + + Return the right sibling of *node*, or the empty string if *node* was the + last child of its parent. + + - *treeName* __numchildren__ *node* + + Return the number of immediate children of *node*. + + - *treeName* __parent__ *node* + + Return the parent of *node*. + + - *treeName* __previous__ *node* + + Return the left sibling of *node*, or the empty string if *node* was the + first child of its parent. + + - *treeName* __set__ *node* ?__-key__ *key*? ?*value*? + + Set or get one of the keyed values associated with a node. If no key is + specified, the key __data__ is assumed. Each node that is added to a tree + has the value "" assigned to the key __data__ automatically. A node may have + any number of keyed values associated with it. If *value* is not specified, + this command returns the current value assigned to the key; if *value* is + specified, this command assigns that value to the key. + + - *treeName* __size__ ?*node*? + + Return a count of the number of descendants of the node *node*; if no node + is specified, __root__ is assumed. + + - *treeName* __splice__ *parent* *from* ?*to*? ?*child*? + + Insert a node named *child* into the tree as a child of the node *parent*. + If *parent* is __root__, it refers to the root of the tree. The new node + will be added to the parent node's child list at the index given by *from*. + The children of *parent* which are in the range of the indices *from* and + *to* are made children of *child*. If the value of *to* is not specified it + defaults to __end__. If no name is given for *child*, a name will be + generated for the new node. The generated name is of the form *node*__x__, + where __x__ is a number. The return result from this command is the name of + the new node. + + - *treeName* __swap__ *node1* *node2* + + Swap the position of *node1* and *node2* in the tree. + + - *treeName* __unset__ *node* ?__-key__ *key*? + + Removes a keyed value from the node *node*. If no key is specified, the key + __data__ is assumed. + + - *treeName* __walk__ *node* ?__-order__ *order*? ?__-type__ *type*? __-command__ *cmd* + + Perform a breadth-first or depth-first walk of the tree starting at the node + *node*. The type of walk, breadth-first or depth-first, is determined by the + value of *type*; __bfs__ indicates breadth-first, __dfs__ indicates + depth-first. Depth-first is the default. The order of the walk, pre-, post-, + both- or in-order is determined by the value of *order*; __pre__ indicates + pre-order, __post__ indicates post-order, __both__ indicates both-order and + __in__ indicates in-order. Pre-order is the default. + + Pre-order walking means that a parent node is visited before any of its + children. For example, a breadth-first search starting from the root will + visit the root, followed by all of the root's children, followed by all of + the root's grandchildren. Post-order walking means that a parent node is + visited after any of its children. Both-order walking means that a parent + node is visited before *and* after any of its children. In-order walking + means that a parent node is visited after its first child and before the + second. This is a generalization of in-order walking for binary trees and + will do the right thing if a binary is walked. The combination of a + breadth-first walk with in-order is illegal. + + As the walk progresses, the command *cmd* will be evaluated at each node. + Percent substitution will be performed on *cmd* before evaluation, just as + in a __[bind](../../../../index.md#bind)__ script. The following + substitutions are recognized: + + * __%%__ + + Insert the literal % character. + + * __%t__ + + Name of the tree object. + + * __%n__ + + Name of the current node. + + * __%a__ + + Name of the action occurring; one of __enter__, __leave__, or __visit__. + __enter__ actions occur during pre-order walks; __leave__ actions occur + during post-order walks; __visit__ actions occur during in-order walks. + In a both-order walk, the command will be evaluated twice for each node; + the action is __enter__ for the first evaluation, and __leave__ for the + second. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *struct :: tree* of the +[Tcllib Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any +ideas for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[tree](../../../../index.md#tree) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2002 Andreas Kupries ADDED embedded/md/tcllib/files/modules/tar/tar.md Index: embedded/md/tcllib/files/modules/tar/tar.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/tar/tar.md @@ -0,0 +1,204 @@ + +[//000000001]: # (tar - Tar file handling) +[//000000002]: # (Generated from file 'tar.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tar(n) 0.11 tcllib "Tar file handling") + +# NAME + +tar - Tar file creation, extraction & manipulation + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.4 +package require tar ?0.11? + +[__::tar::contents__ *tarball* ?__-chan__?](#1) +[__::tar::stat__ *tarball* ?file? ?__-chan__?](#2) +[__::tar::untar__ *tarball* *args*](#3) +[__::tar::get__ *tarball* *fileName* ?__-chan__?](#4) +[__::tar::create__ *tarball* *files* *args*](#5) +[__::tar::add__ *tarball* *files* *args*](#6) +[__::tar::remove__ *tarball* *files*](#7) + +# DESCRIPTION + +Note: Starting with version 0.8 the tar reader commands (contents, stats, get, +untar) support the GNU LongName extension (header type 'L') for large paths. + + - __::tar::contents__ *tarball* ?__-chan__? + + Returns a list of the files contained in *tarball*. The order is not sorted + and depends on the order files were stored in the archive. + + If the option __-chan__ is present *tarball* is interpreted as an open + channel. It is assumed that the channel was opened for reading, and + configured for binary input. The command will *not* close the channel. + + - __::tar::stat__ *tarball* ?file? ?__-chan__? + + Returns a nested dict containing information on the named ?file? in + *tarball*, or all files if none is specified. The top level are pairs of + filename and info. The info is a dict with the keys "__mode__ __uid__ + __gid__ __size__ __mtime__ __type__ __linkname__ __uname__ __gname__ + __devmajor__ __devminor__" + + % ::tar::stat tarball.tar + foo.jpg {mode 0644 uid 1000 gid 0 size 7580 mtime 811903867 type file linkname {} uname user gname wheel devmajor 0 devminor 0} + + If the option __-chan__ is present *tarball* is interpreted as an open + channel. It is assumed that the channel was opened for reading, and + configured for binary input. The command will *not* close the channel. + + - __::tar::untar__ *tarball* *args* + + Extracts *tarball*. *-file* and *-glob* limit the extraction to files which + exactly match or pattern match the given argument. No error is thrown if no + files match. Returns a list of filenames extracted and the file size. The + size will be null for non regular files. Leading path seperators are + stripped so paths will always be relative. + + * __-dir__ dirName + + Directory to extract to. Uses __pwd__ if none is specified + + * __-file__ fileName + + Only extract the file with this name. The name is matched against the + complete path stored in the archive including directories. + + * __-glob__ pattern + + Only extract files patching this glob style pattern. The pattern is + matched against the complete path stored in the archive. + + * __-nooverwrite__ + + Dont overwrite files that already exist + + * __-nomtime__ + + Leave the file modification time as the current time instead of setting + it to the value in the archive. + + * __-noperms__ + + In Unix, leave the file permissions as the current umask instead of + setting them to the values in the archive. + + * __-chan__ + + If this option is present *tarball* is interpreted as an open channel. + It is assumed that the channel was opened for reading, and configured + for binary input. The command will *not* close the channel. + + % foreach {file size} [::tar::untar tarball.tar -glob *.jpg] { + puts "Extracted $file ($size bytes)" + } + + - __::tar::get__ *tarball* *fileName* ?__-chan__? + + Returns the contents of *fileName* from the *tarball*. + + % set readme [::tar::get tarball.tar doc/README] { + % puts $readme + } + + If the option __-chan__ is present *tarball* is interpreted as an open + channel. It is assumed that the channel was opened for reading, and + configured for binary input. The command will *not* close the channel. + + An error is thrown when *fileName* is not found in the tar archive. + + - __::tar::create__ *tarball* *files* *args* + + Creates a new tar file containing the *files*. *files* must be specified as + a single argument which is a proper list of filenames. + + * __-dereference__ + + Normally __create__ will store links as an actual link pointing at a + file that may or may not exist in the archive. Specifying this option + will cause the actual file point to by the link to be stored instead. + + * __-chan__ + + If this option is present *tarball* is interpreted as an open channel. + It is assumed that the channel was opened for writing, and configured + for binary output. The command will *not* close the channel. + + % ::tar::create new.tar [glob -nocomplain file*] + % ::tar::contents new.tar + file1 file2 file3 + + - __::tar::add__ *tarball* *files* *args* + + Appends *files* to the end of the existing *tarball*. *files* must be + specified as a single argument which is a proper list of filenames. + + * __-dereference__ + + Normally __add__ will store links as an actual link pointing at a file + that may or may not exist in the archive. Specifying this option will + cause the actual file point to by the link to be stored instead. + + * __-prefix__ string + + Normally __add__ will store files under exactly the name specified as + argument. Specifying a ?-prefix? causes the *string* to be prepended to + every name. + + * __-quick__ + + The only sure way to find the position in the *tarball* where new files + can be added is to read it from start, but if *tarball* was written with + a "blocksize" of 1 (as this package does) then one can alternatively + find this position by seeking from the end. The ?-quick? option tells + __add__ to do the latter. + + - __::tar::remove__ *tarball* *files* + + Removes *files* from the *tarball*. No error will result if the file does + not exist in the tarball. Directory write permission and free disk space + equivalent to at least the size of the tarball will be needed. + + % ::tar::remove new.tar {file2 file3} + % ::tar::contents new.tar + file3 + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *tar* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[archive](../../../../index.md#archive), [tape +archive](../../../../index.md#tape_archive), [tar](../../../../index.md#tar) + +# CATEGORY + +File formats ADDED embedded/md/tcllib/files/modules/tepam/tepam_argument_dialogbox.md Index: embedded/md/tcllib/files/modules/tepam/tepam_argument_dialogbox.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/tepam/tepam_argument_dialogbox.md @@ -0,0 +1,894 @@ + +[//000000001]: # (tepam::argument_dialogbox - Tcl's Enhanced Procedure and Argument Manager) +[//000000002]: # (Generated from file 'tepam_argument_dialogbox.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tepam::argument_dialogbox(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager") + +# NAME + +tepam::argument_dialogbox - TEPAM argument_dialogbox, reference manual + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [ARGUMENT DIALOGBOX CALL](#section2) + + - [Context Definition Items](#subsection1) + + - [Formatting and Display Options](#subsection2) + + - [Global Custom Data Validation](#subsection3) + + - [Data Entry Widget Items](#subsection4) + + - [Entry Widget Item Attributes](#subsection5) + + - [APPLICATION SPECIFIC ENTRY WIDGETS](#section3) + + - [VARIABLES](#section4) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.3 +package require Tk 8.3 +package require tepam ?0.5? + +[__tepam::argument_dialogbox__ *item_name item_attributes ?item_name item_attributes? ?...?*](#1) +[__tepam::argument_dialogbox__ {*item_name item_attributes ?item_name item_attributes? ?...?*}](#2) + +# DESCRIPTION + +# ARGUMENT DIALOGBOX CALL + +The TEPAM __argument_dialogbox__ is a flexible and easily usable data entry form +generator that is available if Tk has been loaded. Each data entry element of a +form is defined via a *data entry item* that can be provided to +__argument_dialogbox__ in two formats: + + - __tepam::argument_dialogbox__ *item_name item_attributes ?item_name item_attributes? ?...?* + + Using this first format, each *data entry item* is defined via a pair of two + arguments. The first one is the *item name* that defines the entry widget + that has to be used in the form. The second argument, called *item + attributes*, specifies the variable which is attributed to the data entry + element as well as eventual formatting and context information. + + The __argument_dialogbox__ returns __ok__ if the entered data have been + acknowledged (via the *OK* button) and validated by a data checker. If the + entered data have been rejected (via the *Cancel* button) the + __argument_dialogbox__ returns __cancel__. + + A small example illustrates how the __argument_dialogbox__ can be employed: + + set DialogResult [__tepam::argument_dialogbox__ \ + __-title__ "Itinerary selection" \ + __-file__ {*-label "Itinerary report" -variable report_file*} \ + __-frame__ {*-label "Itinerary start"*} \ + __-comment__ {*-text "Specify your itinerary start location"*} \ + __-entry__ {*-label "City" -variable start_city -type string*} \ + __-entry__ {*-label "Street" -variable start_street -type string -optional 1*} \ + __-entry__ {*-label "Street number" -variable start_street_nbr -type integer -optional 1*} \ + __-frame__ {*-label "Itinerary destination"*} \ + __-comment__ {*-text "Specify your itinerary destination"*} \ + __-entry__ {*-label "City" -variable dest_city -type string*} \ + __-entry__ {*-label "Street" -variable dest_street -type string -optional 1*} \ + __-entry__ {*-label "Street number" -variable dest_street_nbr -type integer -optional 1*} \ + __-frame__ {} \ + __-checkbutton__ {*-label "Don't use highways" -variable no_highway*} + + ] This example opens a dialog box that has the title *Itinerary selection*. + A first entry widget in this box allows selecting a report file. It follows + two frames to define respectively an itinerary start and end location. Each + of these locations that are described with a comment has three entry widgets + to specify respectively the city, street and the street number. Bellow the + second frame there is a check button that allows specifying if eventual + highways should be ignored. + + - __tepam::argument_dialogbox__ {*item_name item_attributes ?item_name item_attributes? ?...?*} + + Sometimes it is simpler to provide all the data entry item definitions in + form of a single list to __argument_dialogbox__, and not as individual + arguments. The second format that is supported by __argument_dialogbox__ + corresponds exactly to the first one, except that all item definitions are + packed into a single list that is provided to __argument_dialogbox__. The + previous example can therefore also be written in the following way: + + set DialogResult [__tepam::argument_dialogbox {__ + __-title__ "Itinerary selection" + __-file__ {*-label "Itinerary report" -variable report_file*} + ... + __-checkbutton__ {*-label "Don't use highways" -variable no_highway*} + + __}__] + +The commands __argument_dialogbox__ as well as +__[procedure](../../../../index.md#procedure)__ are exported from the namespace +__tepam__. To use these commands without the __tepam::__ namespace prefix, it is +sufficient to import them into the main namespace: + + __namespace import tepam::*__ + + set DialogResult [__argument_dialogbox__ \ + -title "Itinerary selection" + ... + +The following subsections explain the different argument item types that are +accepted by the __argument_dialogbox__, classified into three groups. The first +data entry item definition format will be used in the remaining document, +knowing that this format can always be transformed into the second format by +putting all arguments into a single list that is then provided to +__argument_dialogbox__. + +## Context Definition Items + +The first item group allows specifying some context aspects of an argument +dialog box. These items are taking a simple character string as item attribute: + + tepam::argument_dialogbox \ + __-__ *string* \ + ... + +The following items are classified into this group: + + - -title *string* + + The dialog box window title which is by default *Dialog* can be changed with + the *-title* item: + + tepam::argument_dialogbox \ + __-title__ "System configuration" \ + ... + + - -window *string* + + The argument dialog box uses by default *.dialog* as dialog top level + window. This path can be changed with the *-window* item: + + tepam::argument_dialogbox \ + __-window__ .dialog \ + ... + + - -parent *string* + + By defining a parent window, the argument dialog box will be displayed + beside this one. Without explicit parent window definition, the top-level + window will be considered as parent window. + + tepam::argument_dialogbox \ + __-parent__ .my_appl \ + ... + + - -context *string* + + If a context is defined the dialog box state, e.g. the entered data as well + as the window size and position, is restored the next time the argument + dialog box is called. The assignment of a context allows saving the dialog + box state in its context to distinguish between different usages of the + argument dialog box. + + tepam::argument_dialogbox \ + __-context__ destination_definitions \ + ... + +## Formatting and Display Options + +Especially for big, complex forms it becomes important that the different data +entry widgets are graphically well organized and commented to provide an +immediate and clear overview to the user. A couple of items allow structuring +and commenting the dialog boxes. + +The items of this classification group require as item attributes a definition +list, which contains itself attribute name and value pairs: + + tepam::argument_dialogbox \ + ... + __-__ { * + ?- ? + ?- ? + ?...?* + } + ... + +The following items are classified into this group: + + - -frame *list* + + The *-frame* item allows packing all following entry widgets into a labeled + frame, until a next frame item is defined or until the last entry widget has + been defined. It recognizes the following attributes inside the item + attribute list: + + * -label *string* + + An optional frame label can be specified with the *-label* statement. + + Example: + + tepam::argument_dialogbox \ + ... + __-frame__ {*-label "Destination address"*} + ... + + To close an open frame without opening a new one, an empty list has to be + provided to the *-frame* statement. + + tepam::argument_dialogbox \ + ... + __-frame__ {} + ... + + - -sep [const {{}}] + + Entry widgets can be separated with the *-sep* statement which doesn't + require additional definitions. The related definition list has to exist, + but its content is ignored. + + tepam::argument_dialogbox \ + ... + __-sep__ {} + ... + + - -comment *string* + + Comments and descriptions can be added with the *-text* attribute of the + *-comment* item. Please note that each entry widget itself can also contain + a *-text* attribute for comments and descriptions. But the *-comment* item + allows for example adding a description between two frames. + + tepam::argument_dialogbox \ + ... + __-comment__ {*-text "Specify bellow the destination address"*} + ... + + - -yscroll __0__|__1__|__auto__ + + This attribute allows controlling an eventual vertical scrollbar. Setting it + to __0__ will permanently disable the scrollbar, setting it to __1__ will + enable it. By default it is set to __auto__. The scrollbar is enabled in + this mode only if the vertical data entry form size exceeds 66% of the + screen height. + + tepam::argument_dialogbox \ + ... + __-yscroll__ __auto__ + ... + +## Global Custom Data Validation + +This item group allows specifying global custom checks to validate the entered +data. + + - -validatecommand *script* + + Custom data checks can be performed via validation commands that are defined + with the *-validatecommand* item. Example: + + tepam::argument_dialogbox \ + -entry {-label "Your comment" -variable YourCom} \ + __-validatecommand__ {IllegalWordDetector $YourCom} + + The validation command is executed in the context of the calling procedure, + once all the basic data checks have been performed and data variables are + assigned. All data is accessed via the data variables. Note that there is + also an entry widget specific attribute *-validatecommand* that allows + declaring custom checks for specific data entries. + + The attribute *-validatecommand* can be repeated to declare multiple custom + checks. + + - -validatecommand_error_text *string* + + This item allows overriding the default error message for a global custom + argument validation (defined by *-validatecommand*). Also this attribute can + be repeated in case multiple checks are declared. + + - -validatecommand2 *script* + + - -validatecommand2_error_text *string* + + These items are mainly for TEPAM internal usage. + + These items corrspond respectively to *-validatecommand* and + *-validatecommand_error_text*. However, the data validation is not performed + in the next upper stack level, but two stack levels higher. + +## Data Entry Widget Items + +Data entry widgets are created with the widget items. These items require as +item attributes a definition list, which contains itself attribute name and +value pairs: + + tepam::argument_dialogbox \ + ... + __-__ { * + ?- ? + ?- ? + ?...?* + } + ... + +The attribute list can contain various attributes to describe and comment an +entry widget and to constrain its entered value. All entry widgets are accepting +a common set of attributes that are described in the section [Entry Widget Item +Attributes](#subsection5). + +TEPAM defines a rich set of entry widgets. If necessary, this set can be +extended with additional application specific entry widgets (see [APPLICATION +SPECIFIC ENTRY WIDGETS](#section3)): + + - -entry *list* + + The *-entry* item generates the simplest but most universal data entry + widget. It allows entering any kind of data in form of single line strings. + + tepam::argument_dialogbox \ + __-entry__ {-label Name -variable Entry} + + - -text *list* + + The *-text* item generates a multi line text entry widget. The widget height + can be selected with the *-height* attribute. + + tepam::argument_dialogbox \ + __-text__ {-label Name -variable Text -height 5} + + - -checkbox *list* + + A group of check boxes is created with the *-checkbox* item. The number of + check boxes and their option values are specified with a list assigned to + the *-choices* attribute or via a variable declared with the + *-choicevariable* attribute: + + tepam::argument_dialogbox \ + __-checkbox__ {-label "Font sytle" -variable FontStyle \ + -choices {bold italic underline} -default italic} + + If the labels of the check boxes should differ from the option values, their + labels can be defined with the *-choicelabels* attribute: + + tepam::argument_dialogbox \ + __-checkbox__ {-label "Font sytle" -variable FontStyle \ + -choices {bold italic underline} \ + -choicelabels {Bold Italic Underline} \ + -default italic} + + In contrast to a radio box group, a check box group allows selecting + simultaneously several choice options. The selection is stored for this + reason inside the defined variable in form of a list, even if only one + choice option has been selected. + + - -radiobox *list* + + A group of radio boxes is created with the *-radiobox* item. The number of + radio boxes and their option values are specified with a list assigned to + the *-choices* attribute or via a variable declared with the + *-choicevariable* attribute. + + In contrast to a check box group, a radio box group allows selecting + simultaneously only one choice option. The selected option value is stored + directly, and not in form of a list, inside the defined variable. + + tepam::argument_dialogbox \ + __-radiobox__ {-label "Text adjustment" -variable Adjustment \ + -choices {left center right} -default left} + + If the labels of the radio boxes should differ from the option values, their + labels can be defined with the *-choicelabels* attribute: + + tepam::argument_dialogbox \ + __-radiobox__ {-label "Text adjustment" -variable Adjustment \ + -choices {left center right} \ + -choicelabels {Left Center Right} -default left} + + - -checkbutton *list* + + The *-checkbutton* entry widget allows activating or deactivating a single + choice option. The result written into the variable will either be __0__ if + the check button was not activated or __1__ if it was activated. An + eventually provided default value has also to be either __0__ or __1__. + + tepam::argument_dialogbox \ + __-checkbutton__ {-label Capitalize -variable Capitalize -default 1} + +Several types of list and combo boxes are available to handle selection lists. + + - -combobox *list* + + The combobox is a combination of a normal entry widget together with a + drop-down list box. The combobox allows selecting from this drop-down list + box a single element. The list of the available elements can be provided + either as a list to the *-choices* attribute, or via a variable that is + specified with the *-choicevariable* attribute. + + tepam::argument_dialogbox \ + __-combobox__ {-label "Text size" -variable Size -choices {8 9 10 12 15 18} -default 12} + + And here is an example of using a variable to define the selection list: + + set TextSizes {8 9 10 12 15 18} + tepam::argument_dialogbox \ + __-combobox__ {-label "Text size" -variable Size -choicevariable TextSizes -default 12} + + - -listbox *list* + + In contrast to the combo box, the list box is always displayed by the + *listbox* entry widget. Only one element is selectable unless the + *-multiple_selection* attribute is set. The list box height can be selected + with the *-height* attribute. If the height is not explicitly defined, the + list box height is automatically adapted to the argument dialog box size. + The first example uses a variable to define the available choices: + + set set AvailableSizes + for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [expr 1<<$k]} + + tepam::argument_dialogbox \ + __-listbox__ {-label "Distance" -variable Distance \ + -choicevariable AvailableSizes -default 6 -height 5} + + Here is a multi-element selection example. Please note that also the default + selection can contain multiple elements: + + tepam::argument_dialogbox \ + __-listbox__ {-label "Text styles" -variable Styles \ + -choices {bold italic underline overstrike} \ + -choicelabels {Bold Italic Underline Overstrike} \ + -default {bold underline} -multiple_selection 1 \ + -height 3} + + - -disjointlistbox *list* + + A disjoint list box has to be used instead of a normal list box if the + selection order is important. The disjoint list box entry widget has in fact + two list boxes, one to select elements and one to display the selected + elements in the chosen order. + + Disjoint listboxes allow always selecting multiple elements. With the + exception of the *-multiple_selection* attribute, disjointed list boxes are + accepting the same attributes as the normal listbox, e.g. *-height, + -choices, -choicevariable, -default*. + + tepam::argument_dialogbox \ + __-disjointlistbox__ {-label "Preferred scripting languages" -variable Languages \ + -comment "Please select your preferred languages in the order" \ + -choices {JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl} \ + -default {Tcl Perl Python}} + +The file and directory selectors are building a next group of data entry +widgets. A paragraph of section [Entry Widget Item Attributes](#subsection5) +explains the widget specific attributes that allow specifying the targeted file +types, active directory etc. + + - -file *list* + + The item *-file* creates a group composed by an entry widget together with a + button that allows opening a file browser. The data type *file* is + automatically selected for this entry if no data type has been explicitly + defined with the *-type* attribute. + + tepam::argument_dialogbox \ + __-file__ {-label "Image file" -variable ImageF \ + -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \ + -initialfile "picture.gif"} + + - -existingfile *list* + + The item *-existingfile* creates a group composed by an entry widget + together with a button that allows opening a browser to select an existing + file. The data type *existingfile* is automatically selected for this entry + if no data type has been explicitly defined with the *-type* attribute. + + tepam::argument_dialogbox \ + __-existingfile__ {-label "Image file" -variable ImageF \ + -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \ + -initialfile "picture.gif"} + + - -directory *list* + + The item *-directory* creates a group composed by an entry widget together + with a button that allows opening a directory browser. The data type + *directory* is automatically selected for this entry if no data type has + been explicitly defined with the *-type* attribute. + + tepam::argument_dialogbox \ + __-directory__ {-label "Report directory" -variable ReportDir} + + - -existingdirectory *list* + + The item *-existingdirectory* creates a group composed by an entry widget + together with a button that allows opening a browser to select an existing + directory. The data type *existingdirectory* is automatically selected for + this entry if no data type has been explicitly defined with the *-type* + attribute. + + tepam::argument_dialogbox \ + __-existingdirectory__ {-label "Report directory" -variable ReportDir} + +Finally, there is a last group of some other special data entry widgets. + + - -color *list* + + The color selector is composed by an entry widget together with a button + that allows opening a color browser. The data type *color* is automatically + selected for this entry widget type if no data type has been explicitly + defined with the *-type* attribute. + + tepam::argument_dialogbox \ + __-color__ {-label "Background color" -variable Color -default red} + + - -font *list* + + The font selector is composed by an entry widget together with a button that + allows opening a font browser. The data type *font* is automatically + selected for this entry widget type if no data type has been explicitly + defined with the *-type* attribute. The entry widget displays an example + text in the format of the selected font. + + The font browser allows selecting by default the font families provided by + the __font families__ Tk command as well as a reasonable set of different + font sizes between 6 points and 40 points. Different sets of font families + and font sizes can be specified respectively via the *-font_families* or + *-font_sizes* attributes. + + If no default font is provided via the *-default* attribute, the default + font of the label widget to display the selected font will be used as + default selected font. If the font family of this label widget is not part + of the available families the first available family is used as default. If + the font size of this label widget is not part of the available sizes the + next close available size is selected as default size. + + tepam::argument_dialogbox \ + __-font__ {-label "Font" -variable Font \ + -font_sizes {8 10 12 16} \ + -default {Arial 20 italic}} + +## Entry Widget Item Attributes + +All the entry widget items are accepting the following attributes: + + - -text *string* + + Eventual descriptions and comments specified with the *-text* attribute are + displayed above the entry widget. + + tepam::argument_dialogbox \ + -entry {__-text "Please enter your name bellow"__ -variable Name} + + - -label *string* + + The label attribute creates left to the entry widget a label using the + provided string as label text: + + tepam::argument_dialogbox \ + -entry {__-label Name__ -variable Name} + + - -variable *string* + + All entry widgets require a specified variable. After accepting the entered + information with the OK button, the entry widget data is stored inside the + defined variables. + + tepam::argument_dialogbox \ + -existingdirectory {-label "Report directory" __-variable ReportDir__} + + - -default *string* + + Eventual default data for the entry widgets can be provided via the + *-default* attribute. The default value is overridden if an argument dialog + box with a defined context is called another time. The value acknowledged in + a previous call will be used in this case as default value. + + tepam::argument_dialogbox \ + -checkbox {-label "Font sytle" -variable FontStyle \ + -choices {bold italic underline} __-default italic__} + + - -optional __0__|__1__ + + Data can be specified as optional or mandatory with the *-optional* + attribute that requires either __0__ (mandatory) or __1__ (optional) as + attribute data. + + In case an entry is optional and no data has been entered, e.g. the entry + contains an empty character string, the entry will be considered as + undefined and the assigned variable will not be defined. + + tepam::argument_dialogbox \ + -entry {-label "City" -variable start_city -type string} \ + -entry {-label "Street" -variable start_street -type string __-optional 0__} \ + -entry {-label "Street number" -variable start_street_nbr -type integer __-optional 1__} \ + + - -type *string* + + If the data type is defined with the *-type* attribute the argument dialog + box will automatically perform a data type check after acknowledging the + entered values and before the dialog box is closed. If a type incompatible + value is found an error message box appears and the user can correct the + value. + + The argument dialog box accepts all types that have been specified by the + TEPAM package and that are also used by + __[tepam::procedure](tepam_procedure.md)__ (see the *tepam::procedure + reference manual*). + + Some entry widgets like the file and directory widgets, as well as the color + and font widgets are specifying automatically the default data type if no + type has been specified explicitly with the *-type* attribute. + + tepam::argument_dialogbox \ + __-entry__ {-label "Street number" -variable start_street_nbr __-type integer__} \ + + - -range *string* + + Values can be constrained with the *-range* attribute. The valid range is + defined with a list containing the minimum valid value and a maximum valid + value. + + The *-range* attribute has to be used only for numerical arguments, like + integers and doubles. + + tepam::argument_dialogbox \ + -entry {-label Month -variable Month -type integer __-range {1 12}__} + + - -validatecommand *string* + + Custom argument value validations can be performed via specific validation + commands that are defined with the *-validatecommand* attribute. The + provided validation command can be a complete script in which the pattern + *%P* is placeholder for the argument value that has to be validated. + + tepam::argument_dialogbox \ + -entry {-label "Your comment" -variable YourCom \ + __-validatecommand__ "IllegalWordDetector %P"} + + While the purpose of this custom argument validation attribute is the + validation of a specific argument, there is also a global data validation + attribute *-validatecommand* that allows performing validation that involves + multiple arguments. + + - -validatecommand_error_text *string* + + This attribute allows overriding the default error message for a custom + argument validation (defined by *-validatecommand*). + +Some other attributes are supported by the list and combo boxes as well as by +the radio and check buttons. + + - -choices *string* + + Choice lists can directly be defined with the *-choices* attribute. This way + to define choice lists is especially adapted for smaller, fixed selection + lists. + + tepam::argument_dialogbox \ + -listbox {-label "Text styles" -variable Styles \ + __-choices {bold italic underline}__ -default underline + + - -choicelabels *string* *(only check and radio buttons)* + + If the labels of the check and radio boxes should differ from the option + values, they can be defined with the *-choicelabels* attribute: + + tepam::argument_dialogbox \ + -checkbox {-label "Font sytle" -variable FontStyle \ + -choices {bold italic underline} \ + __-choicelabels {Bold Italic Underline}__ + + - -choicevariable *string* + + Another way to define the choice lists is using the *-choicevariable* + attribute. This way to define choice lists is especially adapted for huge + and eventually variable selection lists. + + set TextSizes {8 9 10 12 15 18} + tepam::argument_dialogbox \ + -combobox {-label "Text size" -variable Size __-choicevariable TextSizes__} + + - -multiple_selection __0__|__1__ + + The list box item (__-listbox__) allows by default selecting only one list + element. By setting the *-multiple_selection* attribute to __1__, multiple + elements can be selected. + + tepam::argument_dialogbox \ + -listbox {-label "Text styles" -variable Styles \ + -choices {bold italic underline} -default underline \ + __-multiple_selection 1__ -height 3} + +Some additional attributes are supported by the file and directory selection +widgets. + + - -filetypes *string* + + The file type attribute is used by the __-file__ and __-existingfile__ items + to define the file endings that are searched by the file browser. + + tepam::argument_dialogbox \ + -file {-label "Image file" -variable ImageF \ + __-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}}__} + + - -initialfile *string* + + The initial file used by the file browsers of the __-file__ and + __-existingfile__ widgets are by default the file defined with the + *-default* attribute, unless a file is specified with the *-initialfile* + attribute. + + tepam::argument_dialogbox \ + -file {-variable ImageF __-initialfile "picture.gif"__} + + - -activedir *string* + + The *-activedir* attribute will override the default active search directory + used by the file browsers of all file and directory entry widgets. The + default active search directory is defined by the directory of a specified + initial file (*-initialfile*) if defined, and otherwise by the directory of + the default file/directory, specified with the *-default* attribute. + + tepam::argument_dialogbox \ + -file "-variable ImageF __-activedir $pwd__" + +Finally, there is a last attribute supported by some widgets: + + - -height *string* + + All widgets containing a selection list (__-listbox__, __-disjointlistbox__, + __-font__) as well as the multi line __-text__ widget are accepting the + *-height* attribute that defines the number of displayed rows of the + selection lists. + + tepam::argument_dialogbox \ + -listbox {-label "Text size" -variable Size \ + -choices {8 9 10 12 15 18} -default 12 __-height 3__} + + If the no height has been explicitly specified the height of the widget will + be dynamically adapted to the argument dialog box size. + +# APPLICATION SPECIFIC ENTRY WIDGETS + +An application specific entry widget can be made available to the argument +dialog box by adding a dedicated procedure to the __tepam__ namespace. This +procedure has three arguments; the first one is the widget path, the second one +a subcommand and the third argument has various purposes: + + *proc* tepam::ad_form() {W Command {Par ""}} { + *upvar Option Option; # if required* + *variable argument_dialogbox; # if required* + switch $Command { + "create" + "set_choice" + "set" + "get" + } + } + +__Argument_dialogbox__ takes care about the *-label* and *-text* attributes for +all entry widgets. For any data entry widget it creates a frame into which the +data entry widget components can be placed. The path to this frame is provided +via the *W* argument. + +The entry widget procedure has to support 3 mandatory and an optional command +that are selected via the argument *Command*: + + - *create* + + The entry widget is called a first time with the command *create* to build + the data entry widget. + + The frames that are made available by __argument_dialogbox__ for the entry + widgets are by default only extendable in the X direction. To make them also + extendable in the Y direction, for example for extendable list boxes, the + command __ad_form(make_expandable) $W__ has to be executed when an entry + widget is built. + + - *set_choice* + + The entry widget procedure is only called with the *set_choice* command if + the *-choices* or *-choicevariable* has been specified. The command is + therefore only relevant for list and combo boxes. + + The available selection list that is either specified with the *-choices* or + *-choicevariable* attribute is provided via the *Par* argument to the entry + widget procedure. This list can be used to initialize an available choice + list. + + - *set* + + If a default value is either defined via the *-default* attribute or via a + preceding call the entry widget procedure is called with the *set* command. + The argument *Par* contains in this case the value to which the entry widget + has to be initialized. + + - *get* + + The entry widget procedure command *get* has to return the current value of + the entry widget. + +Eventually specified entry widget item attributes are available via the +__Option__ array variable of the calling procedure. This variable becomes +accessible inside the entry widget procedure via the __upvar__ command. + +There may be a need to store some information in a variable. The array variable +__argument_dialogbox__ has to be used for this purpose together with array +indexes starting with *"$W,"*, e.g. *argument_dialogbox($W,values)*. + +Examples of entry widget procedures are directly provided by the TEPAM package +source file that specifies the standard entry widget procedures. The simplest +procedure is the one for the basic *entry* widget: + + proc tepam::ad_form(entry) {W Command {Par ""}} { + switch $Command { + "create" {pack [entry \$W.entry] -fill x \ + -expand yes -pady 4 -side left} + "set" {\$W.entry insert 0 $Par} + "get" {return [\$W.entry get]} + } + } + +It is also possible to relay on an existing entry widget procedure to derive a +new, more specific one. The *radiobox* widget is used for example, to create a +new entry widget that allows selecting either *left*, *center* or *right*. The +original *radiobox* widget is called with the *set_choice* command immediately +after the *create* command, to define the fixed list of selection options. + + proc tepam::ad_form(rcl) {W Command {Par ""}} { + set Res [ad_form(radiobox) $W $Command $Par] + if {$Command=="create"} { + ad_form(radiobox) $W set_choice {left center right} + } + return $Res + } + +Please consult the TEPAM package source file to find additional and more complex +examples of entry widget procedures. + +# VARIABLES + +The __argument_dialogbox__ is using two variables inside the namespace +__::tepam__: + + - __argument_dialogbox__ + + Application specific entry widget procedures can use this array variable to + store their own data, using as index the widget path provided to the + procedure, e.g. *argument_dialogbox($W,)*. + + - __last_parameters__ + + This array variable is only used by an argument dialog box if its context + has been specified via the *-context* attribute. The argument dialog box + position and size as well as its entered data are stored inside this + variable if the data are acknowledged and the form is closed. This allows + the form to restore its previous state once it is called another time. + + To reuse the saved parameters not just in the actual application session but + also in another one, it is sufficient to store the __last_parameter__ array + variable contents in a configuration file which is loaded the next time an + application is launched. + +# SEE ALSO + +[tepam(n)](tepam_introduction.md), [tepam::procedure(n)](tepam_procedure.md) + +# KEYWORDS + +[data entry form](../../../../index.md#data_entry_form), [parameter entry +form](../../../../index.md#parameter_entry_form) + +# CATEGORY + +Argument entry form, mega widget + +# COPYRIGHT + +Copyright © 2009-2013, Andreas Drollinger ADDED embedded/md/tcllib/files/modules/tepam/tepam_doc_gen.md Index: embedded/md/tcllib/files/modules/tepam/tepam_doc_gen.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/tepam/tepam_doc_gen.md @@ -0,0 +1,550 @@ + +[//000000001]: # (tepam::doc_gen - Tcl's Enhanced Procedure and Argument Manager) +[//000000002]: # (Generated from file 'tepam_doc_gen.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tepam::doc_gen(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager") + +# NAME + +tepam::doc_gen - TEPAM DOC Generation, reference manual + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [ARGUMENTS](#section2) + + - [PREDEFINED DOCUMENT FORMATS](#section3) + + - [TXT - Text format](#subsection1) + + - [HTML - HTML format](#subsection2) + + - [POD - Perl document format](#subsection3) + + - [DT - TclLib DocTools format](#subsection4) + + - [ADDING SUPPORT FOR NEW DOCUMENT FORMATS](#section4) + + - [EXAMPLES](#section5) + + - [tepam::doc_gen::generate](#subsection5) + + - [tepam::doc_gen::patch](#subsection6) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.3 +package require tepam 0.5 +package require tepam::doc_gen ?0.1? + +[__tepam::doc_gen::generate__ ?-format *format*? ?-style *style*? ?-header_footer? ?-dest_file *dest_file*? *name*](#1) +[__tepam::doc_gen::patch__ ?-format *format*? ?-style *style*? ?-search_pattern *search_pattern*? ?-src_string *src_string* | -src_file *src_file*? ?-dest_file *dest_file*? ?name?](#2) + +# DESCRIPTION + +This package generates documentations of TEPAM procedures (procedures that have +been declared with __[tepam::procedure](tepam_procedure.md)__). The documents +are generated in the classic UNIX document style using the following document +sections: Name, Synopsis, Description, Arguments and Example. __TEPAM Doc Gen__ +provides support for various document formats. Support for additional formats +can be added if necessary. + +The __TEPAM Doc Gen__ package provides the following commands: + + - __tepam::doc_gen::generate__ ?-format *format*? ?-style *style*? ?-header_footer? ?-dest_file *dest_file*? *name* + + This command generates the documentation for a specified procedure (*name*) + in one of the supported formats (TXT, HTML, POD (Perl Doc), DT (TclLib + DocTool), or in a custom specific format. The format is specified via + ?format?. The flag ?-header_footer? adds to the documentation file header + and footer. If ?dest_file? is specified the documentation is stored in a + file (the file header and footer are added automatically in this case) and + the file name is returned. Otherwise the documentation string is returned by + __generate__. + + - __tepam::doc_gen::patch__ ?-format *format*? ?-style *style*? ?-search_pattern *search_pattern*? ?-src_string *src_string* | -src_file *src_file*? ?-dest_file *dest_file*? ?name? + + This command inserts procedure documentations into an existing master + document at the locations indicated by insertion placeholders which are + matching the pattern of ?search_pattern?. The existing master document is + either provided as data to the argument (?src_string?) or via a file + (?src_file?). The final document is returned by + __[patch](../../../../index.md#patch)__ if no destination file is defined + (?dest_file?). Otherwise, the document is stored in the specified file, and + the number of insertion placeholders that could be handled successfully is + returned. + + Any insertion placeholders of the master document are handled by default. By + defining the argument ?name? the documentation insertion will be restricted + to a particular procedure. + +# ARGUMENTS + + - ?-format *format*? + + Specifies the documentation format. __TEPAM Doc Gen__ provides support for + the following formats: + + TXT - Text format (default) + + HTML + + POD - Perl Plain Old Documentation format (PerlPOD) + + DT - TclLib DocTool format + + Section [ADDING SUPPORT FOR NEW DOCUMENT FORMATS](#section4) shows how + support for additional formats can be added. + + - ?-style *style*? + + The documentation is by default generated in Tcl style (e.g. __command arg1 + arg2 ...__). C-style documentation can be generated by setting this argument + to 'C' (e.g. __command(arg1,arg2,...)__). + + - ?-dest_file *dest_file*? + + If ?dest_file? is defined the documentation is written into the specified + destination file. Otherwise the documentation string is returned by the + commands __generate__ and __[patch](../../../../index.md#patch)__. + + - *name* / ?name? + + This is the name of the procedure for which the documentation has to be + generated. This is a mandatory argument for __generate__, but an optional + argument for __[patch](../../../../index.md#patch)__. + + - ?-header_footer? + + __Generate__ adds to the generated procedure documentation the file header + and footer only if a file is generated. By selecting the flag + ?-header_footer? the header and footer are also generated if the + documentation is returned as string by __generate__. + + - ?-src_string *src_string* | -src_file *src_file*? + + __[Patch](../../../../index.md#patch)__ inserts procedure documentations + into an existing document that is either provided as string to the argument + (?src_string?) or as a file (?src_file?). One of these two arguments need to + be specified. + + - ?-search_pattern *search_pattern*? + + The argument ?search_pattern? defines the documentation insertion + placeholder used in a document. It is a regular expression accepted by + __regexp__ and needs to contain a parenthesized sub-expression that contains + the procedure name for which the documentation needs to be inserted. + + The default insertion placeholder pattern is *\{!(.*?)!\}*, which means that + the procedure name will be embedded between *{!* and *!}*. The section + [EXAMPLES](#section5) contains a custom insertion placeholder pattern + example. + +# PREDEFINED DOCUMENT FORMATS + +__TEPAM Doc Gen__ pre-defines the following document formats: + +## TXT - Text format + +The documentation will be generated in a simple text format if this format is +selected. The format can be customized via the following variable: + + - __tepam::doc_gen::Option(TXT,MaxLineLength)__ + + Default: 80 + + This variable defines the line wrapping limit (character position). + +## HTML - HTML format + +__TEPAM Doc Gen__ generates CSS styled HTML files. The HTML documentation can be +customized via the following variable: + + - __tepam::doc_gen::Option(HTML,CssFile)__ + + Default: "tepam_doc_stylesheet.css" + + This variable specifies the CSS stylesheet file that is referred by the + generated HTML files. + +The CSS stylesheet can be customized to change the documentation formatting. A +good starting point to create a customized CSS stylesheet is to use the CSS file +provided by the __TEPAM Doc Gen__ example/demo. The HTML documentation uses the +following CSS class styles: + + - *h1.tepam_page_title* - Document page title. Only used by __generate__ if a + file is created or if the header and footer are built (flag ?-header_footer? + selected). + + - *div.tepam_command_help* - Documentation container. The entire procedure + documentation is placed inside this container. + + - *p.tepam_section_title* - Section title (e.g. *Name*, *Synopsis*, + *Description*, ...) + + - *p.tepam_sub_section_title* - Sub-section title (used to separate the + documentation of multiple sub-procedures) + + - *p.tepam_name* - Name section + + - *p.tepam_synopsis* - Synopsis section + + - *p.tepam_description* - Single description paragraph + + - *ul.tepam_description_list* - Item of a HTML bulleted/unordered list inside + the description section + + - *dt.tepam_argument* - Item of a HTML description list used to list the + procedure arguments + + - *p.tepam_argument_description* - Argument description paragraph + + - *p.tepam_argument_attribute* - Argument attribute line + + - *pre.tepam_example* - Example section + +## POD - Perl document format + +The documentation is generated in the Perl Plain Old Documentation format +(PerlPOD) if this format is selected. + +## DT - TclLib DocTools format + +The documentation is generated in the Tcllib DocTools format if this format is +selected. + +# ADDING SUPPORT FOR NEW DOCUMENT FORMATS + +Support for a new document format can be added by defining in the +__tepam::doc_gen__ namespace a set of procedures that generate the different +document components. + +The following documentation listing contains tokens that refer to the different +document generation procedures: + + * <01>* + *<03> <20s>* NAME*<20e>* + * <30s>* message_box - Displays text in a message box*<30e>* + * <20s>* SYNOPSYS*<20e>* + * <40s>* message_box [-mtype ] *<40e>* + * <20s>* DESCRIPTION*<20e>* + * <21s> message_box<21e>* + * <54s> message_box [-mtype ] <54e>* + * <50s>* This procedure allows displaying a text in an message box. The following + * * message types are supported:*<50e>* + *<51> <53s>* * Info*<53e>* + * <53s>* * Warning*<53e>* + * <53s>* * Error*<53e>* *<52>* + * <50s>* If the text parameter is use multiple times the different texts are + * * concatenated to create the message text.*<50e>* + * <20s>* ARGUMENTS*<20e>* + *<60> <62s>* [-mtype ]*<62e>* + *<63> <65s>* Message type*<65e>* + * <66s>* Default: "Warning"*<66e>* + * <66s>* Multiple: yes*<66e>* + * <66s>* Choices: Info, Warning, Error*<66e>* *<64>* + * <62s>* *<62e>* + *<63> <65s>* One or multiple text lines to display*<65e>* + * <66s>* Type: string*<66e>* + * <66s>* Multiple: yes*<66e>* *<64><61>* + * <20s>* EXAMPLE*<20e>* + *<70> <72s>* message_box "Please save first the document"*<72e>* + * <73s>* -> 1*<73e>* *<71><04>* + * <02>* + +There are 2 types of document generation procedures: + + - Content generation procedures (e.g. <40s>...<40e>) + + These procedures generate some document content based on the text that is + provided as procedure argument. The listing above shows two tokens for these + procedures to indicate the beginning and the end of the generated content. + + - Control generation procedures (e.g. <03>) + + These procedures generate control constructs, for example to generate the + prolog code and epilog code for lists, sections, etc. These procedures have + no argument. + +The following set of procedures needs to be defined to provide support for a new +document format: + + - *01* - __gen($Format,Header)__ {*Text*} + + Only called if __doc_gen__ generates a file or if it is called with the flag + ?-header_footer?. The procedure creates the file header. The provided + parameter is the procedure name for which the documentation has to be + generated. + + - *02* - __gen($Format,Footer)__ {*Text*} + + Only called if __doc_gen__ generates a file or if it is called with the flag + ?-header_footer?. The procedure creates the file footer. + + - *03* - __gen($Format,Begin)__ {} + + Generates the documentation prolog (preamble) + + - *04* - __gen($Format,End)__ {} + + Generates the documentation epilog + + - *20* - __gen($Format,SectionTitle)__ {*Text*} + + Generates a section title (e.g. *Name*, *Synopsis*, *Description*, ...). The + raw title text is provided as parameter + + - *21* - __gen($Format,SubSectionTitle)__ {*Text*} + + Generates a sub-section title. Sub-sections are used if a single + documentation is generated for multiple sub-commands to make a separation + between them. The raw title text is provided as parameter + + - *30* - __gen($Format,Name)__ {*Text*} + + Generates the name section (without title). The raw section text is provided + as parameter. + + - *40* - __gen($Format,Synopsis)__ {*Text*} + + Generates the synopsis section (without title). The section text provided as + parameter is pre-formatted (the argument strings are generated by + __gen($Format,ArgumentString)__). + + - *50* - __gen($Format,Description)__ {*Text*} + + Generates a description paragraph. The raw paragraph text is provided as + parameter. + + - *51* - __gen($Format,DescriptionListBegin)__ {} + + Generates the prolog of a bulleted/unordered list inside the description + section. This prolog is usually the start code of a list structure. + + - *52* - __gen($Format,DescriptionListEnd)__ {} + + Generates the epilog of a bulleted/unordered list inside the description + section. This epilog is usually the end code of a list structure. + + - *53* - __gen($Format,DescriptionListItem)__ {*Text*} + + Generates a text item in a bulleted/unordered description list. The raw item + text is provided as parameter. + + - *54* - __gen($Format,DescriptionSynopsis)__ {*Text*} + + Generates the synopsis line on the beginning of the description section. The + command can return an empty string if no synopsys line is required at this + place. + + Some formats (e.g. Tcl DocTools) require that the synopsis line is defined + in the description section, to build then automatically the synopsis + section. The section text provided as parameter is pre-formatted (the + argument strings are generated by __gen($Format,ArgumentString)__). + + - *60* - __gen($Format,ArgumentListBegin)__ {} + + Generates the prolog of argument list (definition/non-bulleted list). This + prolog is usually the start code of a definition list. + + - *61* - __gen($Format,ArgumentListEnd)__ {} + + Generates the epilog of the argument list. This epilog is usually the end + string of a list structure. + + - *62* - __gen($Format,ArgumentListItem)__ {Name IsOptional IsNamed Type} + + Generates an argument item line inside the argument list. This command can + rely on __gen($Format,ArgumentDetailBegin)__ since the parameters are + identical. + + - *63* - __gen($Format,ArgumentDetailBegin)__ {} + + Generates the argument details prolog (preamble). + + - *64* - __gen($Format,ArgumentDetailEnd)__ {} + + Generates the argument details epilog + + - *65* - __gen($Format,ArgumentDescription)__ {*Text*} + + Generates the argument description (single paragraph). + + - *66* - __gen($Format,ArgumentAttribute)__ {*Text*} + + Generates a single argument attribute string. The command is called + individually for each attribute. + + - *70* - __gen($Format,ExampleBegin)__ {} + + Generates the example section prolog (preamble) + + - *71* - __gen($Format,ExampleEnd)__ {} + + Generates the example section epilog + + - *72* - __gen($Format,ExampleCommandLine)__ {*Text*} + + Generates a single command line in the example section. The command is + called for each individual command line. + + - *73* - __gen($Format,ExampleResultLine)__ {*Text*} + + Generates a command result line + + - *80* - __gen($Format,ArgumentString)__ {Name IsOptional IsNamed Type} + + Generates the part of the command line or the synopsis that is specific to + an argument. The generated string has to indicate if an argument is + optional, named and if it is a flag. + + The following parameters are provided to this procedure: + + * *Name* + + Name of the argument + + * *IsOptional* + + If true (=__1__) the argument is optional which should be indicated by + the generated string (for example by putting the argument into brackets + {[]} or into question marks '?'): + + gen(TXT,ArgumentString) mtype 1 0 string -> + + *"[mtype]"* + + * *IsNamed* + + If true (=__1__) an argument is a named argument (option). The generated + string should in this case contain the argument/option name, followed by + the argument itself: + + gen(TXT,ArgumentString) mtype 0 1 string -> + + *"-mtype "* Named arguments can also be optional: + + gen(TXT,ArgumentString) mtype 1 1 string -> + + *"[-mtype ]"* + + * *Type* + + Indicates the type of the argument. If the type is set to __none__ the + argument is a flag, which needs to be indicated by the generated string. + Example: + + gen(TXT,ArgumentString) close 1 1 none -> + + *"[-close]"* + +# EXAMPLES + +## tepam::doc_gen::generate + +The __TEPAM Doc Gen__ package can be explored by generating the documentation of +the command __tepam::doc_gen::generate__. The following example generates the +document in text format (default format): + + __tepam::doc_gen::generate__ tepam::doc_gen::generate + +The next example generates the documentation in HTML format: + + __tepam::doc_gen::generate__ -format HTML tepam::doc_gen::generate + +The flag ?header_footer? adds also the file header and footer: + + __tepam::doc_gen::generate__ -format HTML -header_footer tepam::doc_gen::generate + +The documentation can directly be stored in a file. The file header and footer +are automatically generated in this way: + + __tepam::doc_gen::generate__ -format HTML -dest_file doc_gen.html tepam::doc_gen::generate + +The generated HTML file refers a CSS stylesheet file (default: +tepam_doc_stylesheet.css). To display the HTML file correctly this CSS +stylesheet file needs to be copied into the directory of the generated HTML +file. + +The Tcl DOC Tools format can be used as intermediate format to generate other +formats, for example HTML: + + *# Generate the documentation in Tcl Doc Tool format* + set dt [__tepam::doc_gen::generate__ -format DT -header_footer tepam::doc_gen::generate] + ** + *# Create a new doc tools object (HTML format)* + package require doctools + ::doctools::new myDoc -format html + ** + *# Open the HTML file, and write the HTML formatted documentation* + set fHtml [open doc_gen.dt.html w] + puts $fHtml [myDoc format $dt] + close $fHtml + +## tepam::doc_gen::patch + +While __generate__ provides a limited number of possibilities to vary the +document structure, __[patch](../../../../index.md#patch)__ offers more +flexibility. Multiple documentations for different procedures and meta +information can for example be added. + +The following listing shows how the __[patch](../../../../index.md#patch)__ +command works. It defines first a HTML master document string that contains 2 +procedure documentation placeholders (*{**}*). There placeholders +are replaced by __[patch](../../../../index.md#patch)__ with the generated +documentation of the referred procedures. Since nonstandard placeholders are +used, __[patch](../../../../index.md#patch)__ is called with an explicit +placeholder pattern definition (argument *search_pattern*). + + *# Define the HTML master document* + set HtmlMasterDoc {\ + + + tepam::doc_gen + + + + +

tepam::doc_gen

Generate

+ __{*tepam::doc_gen::generate*}__ +

Patch

+ __{*tepam::doc_gen::patch*}__ + + \ + } + ** + *# Patch the master document: This will replace the placeholders by the + # procedure documentation divisions:* + __tepam::doc_gen::patch__ -format HTML -search_pattern {\{\*(.*?)\*\}} \ + -src_string $HtmlMasterDoc -dest_file tepam_doc_gen.html + +# SEE ALSO + +[tepam(n)](tepam_introduction.md), [tepam::procedure(n)](tepam_procedure.md) + +# KEYWORDS + +[automatic documentation](../../../../index.md#automatic_documentation), +[documentation](../../../../index.md#documentation), [procedure +documentation](../../../../index.md#procedure_documentation) + +# CATEGORY + +Documentation tools + +# COPYRIGHT + +Copyright © 2013, Andreas Drollinger ADDED embedded/md/tcllib/files/modules/tepam/tepam_introduction.md Index: embedded/md/tcllib/files/modules/tepam/tepam_introduction.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/tepam/tepam_introduction.md @@ -0,0 +1,431 @@ + +[//000000001]: # (tepam - Tcl's Enhanced Procedure and Argument Manager) +[//000000002]: # (Generated from file 'tepam_introduction.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tepam(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager") + +# NAME + +tepam - An introduction into TEPAM, Tcl's Enhanced Procedure and Argument +Manager + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + + - [OVERVIEW](#section2) + + - [PROCEDURE DECLARATION](#section3) + + - [PROCEDURE HELP](#section4) + + - [PROCEDURE CALL](#section5) + + - [INTERACTIVE PROCEDURE CALLS](#section6) + + - [FLEXIBLE ARGUMENT DIALOG BOX](#section7) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# DESCRIPTION + +This document is an informal introduction into TEPAM, the Tcl's Enhanced +Procedure and Argument Manager. Detailed information to the TEPAM package is +provided in the *tepam::procedure* and *tepam::argument_dialogbox* reference +manuals. + +# OVERVIEW + +This package provides a new Tcl procedure declaration syntax that simplifies the +implementation of procedure subcommands and the handling of the different types +of procedure arguments like flags or switches, options, unnamed arguments, +optional and mandatory options and arguments, default values, etc. Procedure +declarations can be enriched with detailed information about the procedure and +its arguments. This information is used for the following purposes: + +First of all, a preamble is added in front of the body of a procedure that is +declared with TEPAM. This preamble calls an argument manager that that uses the +provided information to check the validity of the argument types and values +before the procedure body is executed. Then, the information is used to generate +help and usage texts if requested, or to generate clear error message in case an +argument validation fails. The information also allows generating automatically +graphical forms that allows an interactive definition of all arguments, in case +a procedure is called interactively. And finally, the additional information +helps self-commenting in a clean way the declaration of a procedure and of all +its arguments. + +The graphical form generator that creates the necessary argument specification +forms for the interactive procedure calls is also available for other purposes +than for procedure argument specifications. It allows creating code efficiently +complex parameter entry forms that are usable independently from TEPAM's new +procedure definition method. + +Here is a short overview about all major TEPAM features: + + - New self-documenting procedure declaration syntax: The additional + information to declare properly a procedure has not to be provided with + additional statements, but can be added in a natural syntax directly into + the procedure header. + + - Easy way to specify subcommands: A subcommand is declared like a procedure, + simply with a procedure name composed by a base name followed by a + subcommand name. Sub-subcommands are created identically using simply + procedure names composed by 3 words. + + - Flexible usage of flags (switches), options (named arguments) and unnamed + arguments. Option names are optionally automatically completed. + + - Support for default values, mandatory/optional options and arguments, choice + lists, value ranges, multiple usable options/arguments. + + - Choice of a *named arguments first, unnamed arguments later* procedure + calling style (typical for Tcl commands) or of an *unnamed arguments first, + named arguments later* procedure calling style (typical for Tk commands). + + - In case the *named arguments first, unnamed arguments later* style (Tcl) is + selected: Clear separation between options and arguments via the "--" flag. + The unnamed arguments can optionally be accessed as options (named + arguments). + + - Automatic type and value check before the procedure body is executed, taking + into account validation ranges, choice lists and custom validation commands. + Generation of clear error message if necessary. + + - Many predefined types exist (integer, boolean, double, color, file, font, + ...). Other application specific types can easily be added. + + - Automatic help and usage text generation if a procedure is called with the + *-help* flag. + + - Automatic generation of an interactive argument definition form, in case a + procedure is called with the *-interactive* flag. + + - Procedure calls can be logged which is useful to get for interactively + called procedures the command call lines. + + - Powerful and code efficient generation of complex parameter definition + forms. + +# PROCEDURE DECLARATION + +TEPAM's procedure declaration syntax is simple and self-explaining. Instead of +declaring a procedure with the Tcl key word +__[proc](../../../../index.md#proc)__, a procedure is declared with the TEPAM +command __[procedure](../../../../index.md#procedure)__ which takes as +__[proc](../../../../index.md#proc)__ also 3 arguments: The procedure name, the +procedure header and the procedure body. + +The following example declares the subcommand +__[message](../../../../index.md#message)__ of the procedure __display__. This +command has several named and unnamed arguments: + + __[tepam::procedure](tepam_procedure.md)__ {display message} { + -return - + -short_description "Displays a simple message box" + -description "This procedure allows displaying a configurable message box." + -args { + {-mtype -default Warning -choices {Info Warning Error} -description "Message type"} + {-font -type font -default {Arial 10 italic} -description "Message text font"} + {-level -type integer -optional -range {1 10} -description "Message level"} + {-fg -type color -default black -description "Message color"} + {-bg -type color -optional -description "Background color"} + {-no_border -type none -description "Use a splash window style (no border)"} + {-log_file -type file -optional -description "Optional message log file"} + {text -type string -multiple -description "Multiple text lines to display"} + } + } { + * puts "display message:" + foreach var {mtype font level fg bg no_border log_file text} { + if {[info exists $var]} { + puts " $var=[set $var]" + } + } + *} + +A call of procedure that has been declared in this way will first invoke the +TEPAM argument manager, before the procedure body is executed. The argument +manager parses the provided arguments, validates them, completes them eventually +with some default values, and makes them finally available to the procedure body +as local variables. In case an argument is missing or has a wrong type, the +argument manager generates an error message that explains the reason for the +error. + +As the example above shows, the TEPAM command +__[procedure](../../../../index.md#procedure)__ accepts subcommand definitions +as procedure name and allows defining much more information than just the +argument list inside the procedure header. The procedure body on the other hand +is identical between a command declared with +__[proc](../../../../index.md#proc)__ and a command declared with +__[procedure](../../../../index.md#procedure)__. + +The procedure header allows defining in addition to the arguments some procedure +attributes, like a description, information concerning the return value, etc. +This information is basically used for the automatic generation of comprehensive +help and usage texts. + +A list of argument definition statements assigned to the *-args* argument is +defining the procedure arguments. Each argument definition statement starts with +the argument name, optionally followed by some argument attributes. + +Three types of arguments can be defined: Unnamed arguments, named arguments and +flags. The distinction between the named and unnamed arguments is made by the +first argument name character which is simply "-" for named arguments. A flag is +defined as named argument that has the type *none*. + +Named and unnamed arguments are mandatory, unless they are declared with the +*-optional* flag and unless they have a default value specified with the +*-default* option. Named arguments and the last unnamed argument can have the +attribute *-multiple*, which means that they can be defined multiple times. The +expected argument data type is specified with the *-type* option. TEPAM defines +a large set of standard data types which can easily be completed with +application specific data types. + +The argument declaration order has only an importance for unnamed arguments that +are by default parsed after the named arguments (Tcl style). A variable allows +changing this behavior in a way that unnamed arguments are parsed first, before +the named arguments (Tk style). + +# PROCEDURE HELP + +The declared procedure can simply be called with the *-help* option to get the +information about the usage of the procedure and its arguments: + + __display message__ -help + +* -> NAME display message - Displays a simple message box SYNOPSYS display +message [-mtype ] : Message type, default: "Warning", choices: {Info +Warning Error} [-font ] : Message text font, type: font, default: Arial 10 +italic [-level ] : Message level, type: integer, range: 1..10 [-fg ] +: Message color, type: color, default: black [-bg ] : Background color, +type: color [-no_border ] : Use a splash window style (no border) [-log_file +] : Optional message log file, type: file : Multiple text lines +to display, type: string DESCRIPTION This procedure allows displaying a +configurable message box.* + +# PROCEDURE CALL + +The specified procedure can be called in many ways. The following listing shows +some valid procedure calls: + + __display message__ "The document hasn't yet been saved!" + *-> display message: + mtype=Warning + font=Arial 10 italic + fg=black + no_border=0 + text={The document hasn't yet been saved!}* + + __display message__ -fg red -bg black "Please save first the document" + *-> display message: + mtype=Warning + font=Arial 10 italic + fg=red + bg=black + no_border=0 + text={Please save first the document}* + + __display message__ -mtype Error -no_border "Why is here no border?" + *-> display message: + mtype=Error + font=Arial 10 italic + fg=black + no_border=1 + text={Why is here no border?}* + + __display message__ -font {Courier 12} -level 10 \ + "Is there enough space?" "Reduce otherwise the font size!" + +*-> display message: mtype=Warning font=Courier 12 level=10 fg=black no_border=0 +text={Is there enough space?} {Reduce otherwise the font size!}* The next lines +show how wrong arguments are recognized. The *text* argument that is mandatory +is missing in the first procedure call: + + __display message__ -font {Courier 12} + +* -> display message: Required argument is missing: text* Only known arguments +are accepted: + + __display message__ -category warning Hello + +* -> display message: Argument '-category' not known* Argument types are +automatically checked and an error message is generated in case the argument +value has not the expected type: + + __display message__ -fg MyColor "Hello" + +* -> display message: Argument 'fg' requires type 'color'. Provided value: +'MyColor'* Selection choices have to be respected ... + + __display message__ -mtype Fatal Hello + +* -> display message: Argument (mtype) has to be one of the following elements: +Info, Warning, Error* ... as well as valid value ranges: + + __display message__ -level 12 Hello + +* -> display message: Argument (level) has to be between 1 and 10* + +# INTERACTIVE PROCEDURE CALLS + +The most intuitive way to call the procedure is using an form that allows +specifying all arguments interactively. This form will automatically be +generated if the declared procedure is called with the *-interactive* flag. To +use this feature the Tk library has to be loaded. + + __display message__ -interactive + +The generated form contains for each argument a data entry widget that is +adapted to the argument type. Check buttons are used to specify flags, radio +boxes for tiny choice lists, disjoint list boxes for larger choice lists and +files, directories, fonts and colors can be selected with dedicated browsers. + +After acknowledging the specified argument data via an OK button, the entered +data are first validated, before the provided arguments are transformed into +local variables and the procedure body is executed. In case the entered data are +invalid, a message appears and the user can correct them until they are valid. + +The procedure calls can optionally be logged in a variable. This is for example +useful to get the command call lines of interactively called procedures. + +# FLEXIBLE ARGUMENT DIALOG BOX + +The form generator that creates in the previous example the argument dialog box +for the interactive procedure call is also available for other purposes than for +the definition of procedure arguments. If Tk has been loaded TEPAM provides and +argument dialog box that allows creating complex parameter definition forms in a +very efficient way. + +The following example tries to illustrate the simplicity to create complex data +entry forms. It creates an input mask that allows specifying a file to copy, a +destination folder as well as a checkbox that allows specifying if an eventual +existing file can be overwritten. Comfortable browsers can be used to select +files and directories. And finally, the form offers also the possibility to +accept and decline the selection. Here is the code snippet that is doing all +this: + + __[tepam::argument_dialogbox](tepam_argument_dialogbox.md)__ \ + __-existingfile__ {-label "Source file" -variable SourceFile} \ + __-existingdirectory__ {-label "Destination folder" -variable DestDir} \ + __-checkbutton__ {-label "Overwrite existing file" -variable Overwrite} + +The __argument_dialogbox__ returns __ok__ if the entered data are validated. It +will return __cancel__ if the data entry has been canceled. After the validation +of the entered data, the __argument_dialogbox__ defines all the specified +variables with the entered data inside the calling context. + +An __argument_dialogbox__ requires a pair of arguments for each variable that it +has to handle. The first argument defines the entry widget type used to select +the variable's value and the second one is a lists of attributes related to the +variable and the entry widget. + +Many entry widget types are available: Beside the simple generic entries, there +are different kinds of list and combo boxes available, browsers for existing and +new files and directories, check and radio boxes and buttons, as well as color +and font pickers. If necessary, additional entry widgets can be defined. + +The attribute list contains pairs of attribute names and attribute data. The +primary attribute is *-variable* used to specify the variable in the calling +context into which the entered data has to be stored. Another often used +attribute is *-label* that allows adding a label to the data entry widget. Other +attributes are available that allow specifying default values, the expected data +types, valid data ranges, etc. + +The next example of a more complex argument dialog box provides a good overview +about the different available entry widget types and parameter attributes. The +example contains also some formatting instructions like *-frame* and *-sep* +which allows organizing the different entry widgets in frames and sections: + + set ChoiceList {"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"} + + set Result [__[tepam::argument_dialogbox](tepam_argument_dialogbox.md)__ \ + __-title__ "System configuration" \ + __-context__ test_1 \ + __-frame__ {-label "Entries"} \ + __-entry__ {-label Entry1 -variable Entry1} \ + __-entry__ {-label Entry2 -variable Entry2 -default "my default"} \ + __-frame__ {-label "Listbox & combobox"} \ + __-listbox__ {-label "Listbox, single selection" -variable Listbox1 \ + -choices {1 2 3 4 5 6 7 8} -default 1 -height 3} \ + __-listbox__ {-label "Listbox, multiple selection" -variable Listbox2 + -choicevariable ChoiceList -default {"Choice 2" "Choice 3"} + -multiple_selection 1 -height 3} \ + __-disjointlistbox__ {-label "Disjoined listbox" -variable DisJntListbox + -choicevariable ChoiceList \ + -default {"Choice 3" "Choice 5"} -height 3} \ + __-combobox__ {-label "Combobox" -variable Combobox \ + -choices {1 2 3 4 5 6 7 8} -default 3} \ + __-frame__ {-label "Checkbox, radiobox and checkbutton"} \ + __-checkbox__ {-label Checkbox -variable Checkbox + -choices {bold italic underline} -choicelabels {Bold Italic Underline} \ + -default italic} \ + __-radiobox__ {-label Radiobox -variable Radiobox + -choices {bold italic underline} -choicelabels {Bold Italic Underline} \ + -default underline} \ + __-checkbutton__ {-label CheckButton -variable Checkbutton -default 1} \ + __-frame__ {-label "Files & directories"} \ + __-existingfile__ {-label "Input file" -variable InputFile} \ + __-file__ {-label "Output file" -variable OutputFile} \ + __-sep__ {} \ + __-existingdirectory__ {-label "Input directory" -variable InputDirectory} \ + __-directory__ {-label "Output irectory" -variable OutputDirectory} \ + __-frame__ {-label "Colors and fonts"} \ + __-color__ {-label "Background color" -variable Color -default red} \ + __-sep__ {} \ + __-font__ {-label "Font" -variable Font -default {Courier 12 italic}} + +] The __argument_dialogbox__ defines all the specified variables with the +entered data and returns __ok__ if the data have been validated via the Ok +button. If the data entry is cancelled by activating the Cancel button, the +__argument_dialogbox__ returns __cancel__. + + if {$Result=="cancel"} { + puts "Canceled" + } else { # $Result=="ok" + puts "Arguments: " + foreach Var { + Entry1 Entry2 + Listbox1 Listbox2 DisJntListbox + Combobox Checkbox Radiobox Checkbutton + InputFile OutputFile InputDirectory OutputDirectory + Color Font + } { + puts " $Var: '[set $Var]'" + } + } + +*-> Arguments: Entry1: 'Hello, this is a trial' Entry2: 'my default' Listbox1: +'1' Listbox2: '{Choice 2} {Choice 3}' DisJntListbox: '{Choice 3} {Choice 5}' +Combobox: '3' Checkbox: 'italic' Radiobox: 'underline' Checkbutton: '1' +InputFile: 'c:\tepam\in.txt' OutputFile: 'c:\tepam\out.txt' InputDirectory: +'c:\tepam\input' OutputDirectory: 'c:\tepam\output' Color: 'red' Font: 'Courier +12 italic'* + +# SEE ALSO + +[tepam::argument_dialogbox(n)](tepam_argument_dialogbox.md), +[tepam::procedure(n)](tepam_procedure.md) + +# KEYWORDS + +[argument integrity](../../../../index.md#argument_integrity), [argument +validation](../../../../index.md#argument_validation), +[arguments](../../../../index.md#arguments), [entry +mask](../../../../index.md#entry_mask), [parameter entry +form](../../../../index.md#parameter_entry_form), +[procedure](../../../../index.md#procedure), +[subcommand](../../../../index.md#subcommand) + +# CATEGORY + +Procedures, arguments, parameters, options + +# COPYRIGHT + +Copyright © 2009-2013, Andreas Drollinger ADDED embedded/md/tcllib/files/modules/tepam/tepam_procedure.md Index: embedded/md/tcllib/files/modules/tepam/tepam_procedure.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/tepam/tepam_procedure.md @@ -0,0 +1,1308 @@ + +[//000000001]: # (tepam::procedure - Tcl's Enhanced Procedure and Argument Manager) +[//000000002]: # (Generated from file 'tepam_procedure.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tepam::procedure(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager") + +# NAME + +tepam::procedure - TEPAM procedure, reference manual + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [TERMINOLOGY](#section2) + + - [PROCEDURE DECLARATION](#section3) + + - [Procedure Attributes](#subsection1) + + - [Argument Declaration](#subsection2) + + - [VARIABLES](#section4) + + - [ARGUMENT TYPES](#section5) + + - [Predefined Argument Types](#subsection3) + + - [Defining Application Specific Argument Types](#subsection4) + + - [PROCEDURE CALLS](#section6) + + - [Help](#subsection5) + + - [Interactive Procedure Call](#subsection6) + + - [Unnamed Arguments](#subsection7) + + - [Named Arguments](#subsection8) + + - [Unnamed Arguments First, Named Arguments Later (Tk + Style)](#subsection9) + + - [Named Arguments First, Unnamed Arguments Later (Tcl + Style)](#subsection10) + + - [Raw Argument List](#subsection11) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.3 +package require tepam ?0.5? + +[__tepam::procedure__ *name* *attributes* *body*](#1) + +# DESCRIPTION + +This package provides an alternative way to declare Tcl procedures and to manage +its arguments. There is a lot of benefit to declare a procedure with TEPAM +rather than with the Tcl standard command __proc__: TEPAM allows specifying +inside the procedure declaration all information that is required to generate +comprehensive documentations and help support. The information is also used by +an automatically invoked argument checker that validates the provided procedure +arguments before the procedure body is executed. Finally, a procedure can be +called interactively which will open a graphical form that allows specifying the +procedure arguments. + +TEPAM simplifies also the handling of the different types of argument, like the +*named arguments* (often also called *options*) and the *unnamed arguments*. +TEPAM supports the *named first, unnamed later* style (typical Tcl command +style) as well as also the *unnamed first, named later* style (typical Tk +command style). TEPAM takes care about default values for arguments, optional +arguments, multiple applicable arguments, etc. and eliminates the need to check +the validity of the argument inside the procedure bodies. + +An informal overview of all the TEPAM procedure declaration and calling features +as well as a short introduction into TEPAM is provided by *tepam(n)*. + +# TERMINOLOGY + +The exact meaning of several terms that are used in this document will be +shortly explained to avoid any ambiguities and misunderstandings. + + - *Subcommand* + + The usage of subcommands is heavily used in the Tcl language. Several + commands are incorporated into a single main command and are selectable via + the first argument. + + The __string__ command is an example of such a command that implements for + example subcommands to check a character string length, to compare strings, + to extract substrings, etc: + + __string length__ *string* + __string compare__ *string* *string* + __string range__ *string* *first* *last* + ... + + TEPAM provides a framework that allows implementing easily such subcommands + in form of Tcl procedures. It allows not only defining a first level of + subcommands, but also a higher level of subcommands. The __string__ command + class check could be implemented as independent sub-sub-commands of the + __string__ command: + + __string is alnum__ *string* + __string is integer__ *string* + __string is double__ *string* + ... + + - *Procedure attribute* + + TEPAM allows attaching to a declared procedure different kind of attributes. + Some of these attributes are *just* used for documentation purposes, but + other attributes specify the way how the procedure has to be called. Also + the procedure arguments are defined in form of a procedure attribute. + + - *Argument* + + TEPAM uses the term *argument* for the parameters of a procedure. + + The following example calls the subcommand __string compare__ with several + arguments: + + __string compare__ + + *-nocase -length 3 "emphasized" "emphasised"* The following paragraphs + discuss these different argument types. + + - *Named argument* + + Some parameters, as *-length 3* of the subcommand __string compare__ have to + be provided as pairs of argument names and argument values. This parameter + type is often also called *option*. + + TEPAM uses the term *named argument* for such options as well as for the + flags (see next item). + + - *Flag, switch* + + Another parameter type is the *flag* or the *switch*. Flags are provided + simply by naming the flag leading with the '-' character. The *-nocase* of + the previous __string compare__ example is such a flag. + + *Flags* are considered by TEPAM like a special form of *named arguments*. + + - *Unnamed argument* + + For the other parameters, e.g. the ones for which the argument name has not + to be mentioned, TEPAM uses the term *unnamed argument*. The previous + __string compare__ example uses for the two provided character strings two + *unnamed arguments*. + + - *Argument attribute* + + TEPAM allows describing the purpose of each procedure argument with + *argument attributes*. While some of them are just documenting the + attributes, most attributes are used by an argument manager to control and + validate the arguments that are provided during a procedure call. Argument + attributes are used to specify default values, parameter classes (integer, + xdigit, font, ...), choice validation lists, value ranges, etc. + + - *Named arguments first, unnamed arguments later* + + The __string compare__ command of the previous example requires that the + *named arguments* (options, flags) are provided first. The two mandatory + (unnamed) arguments have to be provided as last argument. + + __string compare__ + + *-nocase -length 3 Water $Text* This is the usual Tcl style (exceptions + exist) which is referred in the TEPAM documentation as *named arguments + first, unnamed arguments later style*. + + - *Unnamed arguments first, named arguments later* + + In contrast to most Tcl commands, Tk uses generally (exceptions exist also + here) a different calling style where the *unnamed arguments* have to be + provided first, before the *named arguments* have to be provided: + + __pack__ + + *.ent1 .ent2 -fill x -expand yes -side left* This style is referred in the + TEPAM documentation as *unnamed arguments first, named arguments later + style*. + +# PROCEDURE DECLARATION + +TEPAM allows declaring new Tcl procedures with the command __tepam::procedure__ +that has similar to the standard Tcl command __proc__ also 3 arguments: + + - __tepam::procedure__ *name* *attributes* *body* + +The TEPAM procedure declaration syntax is demonstrated by the following example: + + __tepam::procedure__ {display message} { + -short_description + "Displays a simple message box" + -description + "This procedure allows displaying a configurable\ + message box. The default message type that is\ + created is a warning, but also errors and info can\ + be generated. + The procedure accepts multiple text lines." + -example + {display message -mtype Warning "Save first your job"} + -args { + {-mtype -choices {Info Warning Error} \ + -default Warning -description "Message type"} + {text -type string -multiple \ + -description "Multiple text lines to display"} + } + } { + puts "Message type: $mtype" + puts "Message: $text" + } + +The 3 arguments of __procedure__ are: + + - *name* + + The procedure name can be used in very flexible ways. Procedure names can + have namespace qualifiers. By providing a two element name list as procedure + name, a subcommand of a procedure will be declared. It is even possible to + declare sub-sub-commands of a procedure by providing name lists with three + elements. + + Here are some valid procedure declarations using different procedure names + (the attribute and body arguments are empty for simplicity): + + *# Simple procedure name:* + tepam::procedure __display_message__ {} {} + ** + *# Procedure declared in the main namespace:* + tepam::procedure __::display_message__ {} {} + ** + *# Procedure in the namespace* __::ns__*:* + tepam::procedure __::ns::display_message__ {} {} + ** + *# Declaration of the subcommand* __message__ *of the procedure* __display__*:* + tepam::procedure __{display message}__ {} {} + + - *attributes* + + All procedure attributes are provided in form of an option list that + contains pairs of option names and option values. The example above has as + procedure attribute a short and a normal description, but also the procedure + arguments are defined in form of a procedure attribute. + + Most procedure attributes are providing information for documentation + purposes. But some of them affect also the way how the procedure can be + called. The section [Procedure Attributes](#subsection1) discusses in detail + the available procedure attributes. + + The procedure arguments are defined in form of a special procedure + attribute. Most of the information provided in the argument definition is + not just used for documentation purposes. This information is in fact used + by the TEPAM argument manager to handle and validate the various forms of + arguments that are provided during the procedure calls. The section + [Argument Declaration](#subsection2) discusses in detail all the argument + definition attributes. + + - *body* + + This is the normal procedure body. The declared arguments will be available + to the procedure body in form of variables. + + The procedure body will only be executed if the provided set of arguments + could be validated by the TEPAM argument manager. + + tepam::procedure {display_message} { + -args { + {-__mtype__ -default Warning -choices {Warning Error}} + {__text__ -type string} + } + } { + puts "Message type: __$mtype__" + puts "Message: __$text__" + } + +The commands __[procedure](../../../../index.md#procedure)__ as well as +__argument_dialogbox__ are exported from the namespace __tepam__. To use these +commands without the __tepam::__ namespace prefix, it is sufficient to import +them into the main namespace: + + __namespace import tepam::*__ + + __[procedure](../../../../index.md#procedure)__ {display_message} { + -args { + ... + +## Procedure Attributes + +The first group of attributes affect the behavior of the declared procedure: + + - -named_arguments_first __0__|__1__ + + This attribute defines the calling style of a procedure. TEPAM uses by + default the *named arguments first, unnamed arguments later* style (Tcl). + This default behavior can globally be changed by setting the variable + __tepam::named_arguments_first__ to __0__. This global calling style can be + changed individually for a procedure with the *-named_arguments_first* + attribute. + + - -auto_argument_name_completion __0__|__1__ + + The declared procedures will by default automatically try to match + eventually abbreviated argument names to the defined arguments names. This + default behavior can globally be changed by setting the variable + __tepam::auto_argument_name_completion__ to __0__. This global setting of + the automatic argument name completion can be changed individually for a + procedure with the *-auto_argument_name_completion* procedure attribute. + + - -interactive_display_format __extended__|__short__ + + A procedure declared with the TEPAM __procedure__ command can always be + called with the __-interactive__ option. By doing so, a graphical form will + be generated that allows specifying all procedure argument values. There are + two display modes for these interactive forms. While the *extended* mode is + more adapted for small procedure argument sets, the __short__ form is more + adequate for huge procedure argument sets. + + The choice to use short or extended forms can be globally configured via the + variable __tepam::interactive_display_format__. This global setting can then + be changed individually for a procedure with the + *-interactive_display_format* procedure attribute. + + - -args *list* + + The procedure arguments are declared via the *-args* attribute. An argument + is defined via a list having as first element the argument name, followed by + eventual argument attributes. All these argument definition lists are + packaged themselves into a global list that is assigned to the *-args* + attribute. + + The argument definition syntax will be described more in detail in the + following sub section. + +The next attributes allow specifying custom argument checks as well as custom +error messages in case these checks are failing: + + - -validatecommand *script* + + Custom argument validations can be performed via specific validation + commands that are defined with the *-validatecommand* attribute. + + Validation command declaration example: + + tepam::procedure {display_message} { + -args { + {text -type string -description "Message text"} } + __-validatecommand {IllegalWordDetector $text}__ + } { + } + + The validation command is executed in the context of the declared procedure + body. The different argument values are accessed via the argument names. + Note there is also an argument attribute *-validatecommand* that allows + declaring custom checks for specific arguments. + + The attribute *-validatecommand* can be repeated to declare multiple custom + checks. + + - -validatecommand_error_text *string* + + This attribute allows overriding the default error message for a custom + argument validation (defined by *-validatecommand*). Also this attribute can + be repeated in case multiple argument checks are declared. + +The following attribute allows controlling the logging settings for an +individual procedure: + + - -command_log __0__|__1__|__"interactive"__ + + This argument configures the logging of the procedure calls into the list + variable __tepam::ProcedureCallLogList__. The default configuration defined + by the variable __tepam::command_log__ will be used if this argument is not + defined in a procedure declaration. + + Setting this argument to __0__ will disable any procedure call loggings, + setting it to __1__ will log any procedure calls and setting it to + __interactive__ will log just the procedures that are called interactively + (procedures called with the __-interactive__ flag). + +The next group of procedure attributes is just used for the purpose of +documentation and help text generation: + + - -category *string* + + A category can be assigned to a procedure for documentation purposes. Any + string is accepted as category. + + - -short_description *string* + + The short description of a procedure is used in the documentation summary of + a generated procedure list as well as in the NAME section of a generated + procedure manual page. + + - -description *string* + + The (full) description assigned to a procedure is used to create user manual + and help pages. + + - -return *string* + + The *-return* attribute allows defining the expected return value of a + procedure (used for documentation purposes). + + - -example *string* + + A help text or manual page of a procedure can be enriched with eventual + examples, using the *-example* attribute. + +## Argument Declaration + +The following example shows the structure that is used for the argument +definitions in the context of a procedure declaration: + + tepam::procedure {display_message} { + -args __{ + {-mtype -default Warning -choices {Info Warning Error} -description "Message type"} + {-font -type font -default {Arial 10 italic} -description "Message text font"} + {-level -type integer -optional -range {1 10} -description "Message level"} + {-fg -type color -optional -description "Message color"} + {-log_file -type file -optional -description "Optional message log file"} + {text -type string -multiple -description "Multiple text lines to display"} + }__ + } { + } + +Each of the procedure arguments is declared with a list that has as first +element the argument name, followed by eventual attributes. The argument +definition syntax can be formalized in the following way: + + tepam::procedure { + -args __{ + { ...} + { ...} + ... + }__ + } + +The argument names and attributes have to be used in the following way: + + - Argument name (*>*) + + The provided argument name specifies whether the argument is an *unnamed + argument* or a *named argument*. In addition to this, an argument name can + also be blank to indicate an argument comment, or it can start with # to + indicate a section comment. + + * *""* + + This is the simplest form of an argument name: An argument whose name is + not starting with '-' is an *unnamed argument*. The parameter provided + during a procedure call will be assigned to a variable with the name + **. + + tepam::procedure {print_string} { + -args { + {__[text](../../../../index.md#text)__ -type string -description "This is an unnamed argument"} + } + } { + puts __$text__ + } + + print_string __"Hello"__ + + * -> Hello* + + * *"-"* + + An argument whose name starts with '-' is a *named argument* (also + called *option*). The parameter provided during a procedure call will be + assigned to a variable with the name ** (not *-*). + + tepam::procedure {print_string} { + -args { + {__-text__ -type string -description "This is a named argument"} + } + } { + puts __$text__ + } + + print_string __-text "Hello"__ + + * -> Hello* + + * *"--"* + + This flag allows clearly specifying the end of the named arguments and + the beginning of the unnamed arguments, in case the *named arguments + first, unnamed arguments later style (Tcl)* has been selected. + + If the *unnamed arguments first, named arguments later style (Tk)* style + is selected, this flag is ignored if the unnamed arguments have already + been parsed. Otherwise it will be assigned to the corresponding unnamed + argument. + + * *"-"* or *""* + + A blank argument name (either '-' or *''*) starts a comment for the + following arguments. + + tepam::procedure {print_time} { + -interactive_display_format short + -args { + {hours -type integer -description "Hour"} + {minutes -type integer -description "Minute"} + + __{- The following arguments are optional:}__ + {seconds -type integer -default 0 -description "Seconds"} + {milliseconds -type integer -default 0 -description "Milliseconds"} + } + } { + puts "${hour}h${minutes}:[expr $seconds+0.001*$milliseconds]" + } + + Argument comments are basically used in the graphical argument + definition forms that are created if a procedure is called + interactively. + + * *"#*"* + + An argument definition list that starts with '#' is considered as a + section comment. The argument definition list will be trimmed from the + '#' characters and the remaining string will be used as section comment. + + Section comments can be used to structure visually the argument + definition code. Section comments are also used to structure the + generated help texts and the interactive argument definition forms. + + tepam::procedure {complex_multiply} { + -description "This function perform a complex multiplication" + -args { + __{#### First complex number ####}__ + {-r0 -type double -description "First number real part"} + {-i0 -type double -description "First number imaginary part"} + + __{#### Second complex number ####}__ + {-r1 -type double -description "Second number real part"} + {-i1 -type double -description "Second number imaginary part"} + } + } { + return [expr $r0*$r1 - $i0*$i1] + } + + - Argument attributes (*> >*) + + The following argument attributes are supported: + + * -description *string* + + The description argument attribute is used for documentation purpose. + Interactive argument definition forms use this attribute to provide + explanations for an argument. + + * -type *type* + + The type argument attribute allows assigning the argument either to a + predefined data type, or to an application specific data type. The + argument values that are provided during a procedure call are + automatically checked with respect to the defined argument type. + + The section [ARGUMENT TYPES](#section5) provides a list of predefined + data types and explains how application specific types can be specified. + + The argument type *none* has a special meaning. An argument that has the + type *none* is handled as a *flag*. A flag is always optional and its + related variable contains the logical value __1__ if the flag has been + defined during the procedure call, or otherwise __0__. + + * -default *value* + + Eventual default values can be defined with the -default argument + attribute. Arguments with default values are automatically optional + arguments. + + * -optional|-mandatory + + Arguments are by default mandatory, unless a default value is defined. + The flag *-optional* transforms an argument into an optional argument. + + In case an optional argument is not defined during a procedure call, the + corresponding variable will not be defined. The flag *-mandatory* is the + opposite to *-optional*. This flag exists only for completion reason, + since an argument is anyway mandatory by default. + + * -multiple + + Arguments that have the *-multiple* attribute can be defined multiple + times during a procedure call. The values that are provided during a + procedure call for such an argument are stored in a list variable. This + is even the case if such an argument is only defined once during a + procedure call. + + The *-multiple* attribute can be attributed to unnamed arguments and to + named arguments. The pair of argument name/argument value has to be + repeated for each provided value in case of a named argument. In case + the argument with the *-multiple* attribute is an unnamed argument, this + one has to be the absolute last one of all unnamed arguments. + + * -choices *list* + + A possible set of valid argument values can be attributed to an argument + via the *-choices* attribute. The argument value provided during a + procedure call will be checked against the provided choice values. + + * -choicelabels *list* + + An eventual short description can be attributed to each choice option + with the *-choicelabels* attribute. These descriptions will be used in + the generated help texts and as radio and check box labels for the + interactive calls. + + The *-choicelabels* attribute is optional, but if it is defined, its + list needs to have the identical size as the *-choices* argument list. + + * -range *{double double}* + + Another argument constraint can be defined with the *-range* attribute. + The valid range is defined with a list containing the minimum valid + value and a maximum valid value. The *-range* attribute has to be used + only for numerical arguments, like integers and doubles. + + * -validatecommand *script* + + Custom argument value validations can be performed via specific + validation commands that are defined with the *-validatecommand* + attribute. The provided validation command can be a complete script in + which the pattern *%P* is replaced by the argument value that has to be + validated. + + Validation command declaration example: + + tepam::procedure {display_message} { + -args { + {text -type string -description "Message text" \ + __-validatecommand {IllegalWordDetector %P}__} + } { + } + + While the purpose of this custom argument validation attribute is the + validation of a specific argument, there is also a global attribute + *-validatecommand* that allows performing validation that involves + multiple arguments. + + * -validatecommand_error_text *string* + + This attribute allows overriding the default error message for a custom + argument validation (defined by *-validatecommand*). + + * -widget *string* + + The widgets that allow defining the different arguments in case of an + interactive procedure call are normally selected automatically in + function of the argument type. The *-widget* attribute allows specifying + explicitly a certain widget type for an argument. + + * -auxargs *list* + + In case a procedure is called interactively, additional argument + attributes can be provided to the interactive argument definition form + via the *-auxargs* attribute that is itself a list of attribute + name/attribute value pairs: + + -auxargs {- \ + - + ... + } + + For example, if a procedure takes as argument a file name it may be + beneficial to specify the required file type for the interactive + argument definition form. This information can be provided via the + *-auxargs* attribute to the argument definition form: + + tepam::procedure LoadPicture { + -args { + {FileName -type existingfile -description "Picture file" \ + __-auxargs {-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}} }}__} + } + } { + } + + * -auxargs_commands *script* + + If the auxiliary argument attributes are not static but have to be + dynamically adaptable, the *-auxargs_commands* allows defining them via + commands that are executed during a procedure call. A list of pairs of + auxiliary attribute names and commands has to be provided to the + *-auxargs_commands* attribute. The provided commands are executed in the + context of the calling procedure. + + -auxargs_commands {- \ + - + ... + } + +# VARIABLES + +Several variables defined inside the __::tepam__ namespace impact the mode of +operation of the procedures that have been declared with the TEPAM __procedure__ +command. + + - __named_arguments_first__ + + This variable defines the general calling style of the procedures. It is by + default set to __1__ which selects the *named arguments first, unnamed + arguments later* style (Tcl style). + + By setting this variable to __0__, the *named arguments first, unnamed + arguments later* style is globally selected (Tk style): + + set tepam::named_arguments_first 0 + + While this variable defines the general calling style, the procedure + attribute *-named_arguments_first* can adapt this style individually for + each declared procedure. + + - __auto_argument_name_completion__ + + This variable controls the general automatic argument name matching mode. By + default it is set to __1__, meaning that the called procedures are trying to + match eventually abbreviated argument names with the declared argument + names. + + By setting this variable to __0__ the automatic argument name matching mode + is disabled: + + set tepam::auto_argument_name_completion 0 + + While this variable defines the general matching mode, the procedure + attribute *-auto_argument_name_completion* can adapt this mode individually + for each declared procedure. + + - __interactive_display_format__ + + A procedure declared via the TEPAM __procedure__ command can always be + called with the __-interactive__ switch. By doing so, a graphical form will + be generated that allows entering interactively all procedure arguments. + + There are two display modes for these interactive forms. The *extended* mode + which is the default mode is more adapted for small procedure argument sets. + The __short__ form is more adequate for huge procedure argument sets: + + set tepam::interactive_display_format "short" + + The choice to use short or extended forms can be globally configured via the + variable __interactive_display_format__. This global setting can be changed + individually for a procedure with the procedure attribute + *-interactive_display_format*. + + - __help_line_length__ + + The maximum line length used by the procedure help text generator can be + specified with this variable. The default length which is set to 80 + (characters) can easily be adapted to the need of an application: + + set tepam::help_line_length 120 + + Since this variable is applied directly during the help text generation, its + value can continuously be adapted to the current need. + + - __command_log__ + + Procedure calls can be logged inside the list variable + __tepam::ProcedureCallLogList__. The variable __tepam::command_log__ + controls the default logging settings for any procedures. The following + configurations are supported: + + *0*: Disables any procedure call loggings + + *1*: Enables any procedure call loggings + + *"interactive"*: Will log any procedures called interactively (e.g. + procedures called with the -interactive flag). This is the default + configuration. + + This default logging configuration can be changed individually for each + procedure with the *-command_log* attribute. + +# ARGUMENT TYPES + +TEPAM provides a comprehensive set of procedure argument types. They can easily +be completed with application specific types if necessary. + +## Predefined Argument Types + +To remember, a type can be assigned to each specified procedure argument: + + tepam::procedure {warning} { + -args { + {-font __-type font__ -default {Arial 10 italic}} + {-severity_level __-type integer__ -optional -range {1 10}} + {-fg __-type color__ -optional -description "Message color"} + {text __-type string__ -multiple -description "Multiple text lines to display"} + } + } { + ... + } + +There are some *special purpose types* that are building the first category of +predefined argument types: + + - __none__ A *flag*, also called *switch*, is defined as a named argument that + has the type __none__. Flags are always optional and the default value of + the assigned variable is set to __0__. In contrast to the (normal) named + arguments, no argument value has to be provided to a flag. + + tepam::procedure flag_test { + -args { + __{-flag -type none -description "This is a flag"}__ + } + } { + puts __$flag__ + } + + flag_test + *-> 0* + + flag_test -flag + + *-> 1* + + Since no argument value has to be provided to a flag, also no data check is + performed for this argument type. + + - __string__ __String__ is a generic argument data type. Any data string can + be provided to a string type argument and no data type checks are therefore + performed. The string type allows defining single line strings during the + interactive procedure calls. + + - __text__ __Text__ is identical to __string__ with the only difference that + it allows entering multi line strings during interactive procedure calls. + + - __{}__ A __blank__ argument type signifies an undefined argument type. This + is the default argument type that will be used if no type has been + explicitly specified. An argument that has a __blank__ type behaves + identically than an argument that has a __string__ type, e.g. no argument + data checks are performed. The only difference is that the data type + __string__ is mentioned in the generated help documentation, while this is + not the case for the __blank__ type. + +Several *numerical types* are defined by TEPAM. The type validation procedures +are using the __string is -strict__ commands to check the validity of the +provided arguments, which assures that no empty strings are accepted as argument +value. The type validation expression for the numerical types and the argument +types to which this expression is applied are: + + string is ____ -strict + +** + + - *boolean* + + - *integer* + + - *double* + +Empty strings are accepted as argument value for all the alpha numeric argument +types. The argument types that are falling into this category and validation +expression used for them are: + + string is ** + +** + + - *alnum* + + - *alpha* + + - *ascii* + + - *control* + + - *digit* + + - *graph* + + - *lower* + + - *print* + + - *punct* + + - *space* + + - *upper* + + - *wordchar* + + - *xdigit* + +In addition to the data types checked with the __string is __ commands, +TEPAM specifies some other useful data types: + + - *char* Each string that has a length of 1 character meets the *character* + type. The type check is made with the following expression: + + expr [string length **]==1 + + - *color* Any character strings that are accepted by Tk as a color are + considered as valid color argument. Please note that the Tk package has to + be loaded to use the type *color*. TEPAM is using the following command to + validate the color type: + + expr ![catch {winfo rgb . **} + + ] + + - *font* Any character strings that are accepted by Tk as a font are + considered as valid font argument. Please note that the Tk package has to be + loaded to use the *font* type. TEPAM is using the following command to + validate the color type: + + expr ![catch {font measure ""} + + ] + + - *file* Any strings that are not containing one of the following characters + are considered as valid file names: * ? " < >. It is not necessary that the + file and its containing directory exist. Zero-length strings are not + considered as valid file names. + + The following expression is used to validate the file names: + + expr [string length ]>0 && ![regexp {[\"*?<>:]} + + ] + + - *existingfile* The argument is valid if it matches with an existing file. + The following check is performed to validate the arguments of this type: + + file exists + + - *directory* The directory argument is validated exactly in the same way as + the file arguments. + + - *existingdirectory* The argument is valid if it matches with an existing + directory. The following check is performed to validate the arguments of + this type: + + file isdirectory + +## Defining Application Specific Argument Types + +To add support for a new application specific argument type it is just necessary +to add into the namespace __tepam__ a validation function +__Validation()__. This function requires one argument. It has to returns +__1__ if the provided argument matches with the relevant data type. The function +has to return otherwise __0__. + +The validation command section of the "tepam.tcl" package provides sufficient +examples of validation functions, since it implements the ones for the standard +TEPAM types. + +The following additional code snippet shows the validation function for a custom +argument type that requires values that have a character string length of +exactly 2: + + proc tepam::Validate(two_char) {v} {expr {[string length $v]==2}} + +# PROCEDURE CALLS + +## Help + +Each procedure can be called with the *-help* flag. The procedure will then +print a generated help text to *stdout* and will then return without performing +any additional actions. + +Taking the first procedure declared in [PROCEDURE CALLS](#section6), the help +request and the printed help text would be: + + __display message -help__ + +*-> NAME display message - Displays a simple message box SYNOPSIS display +message [-mtype ] Message type, default: "Warning", choices: {Info, +Warning, Error} Multiple text lines to display, type: string DESCRIPTION +This procedure allows displaying a configurable message box. The default message +type that is created is a warning, but also errors and info can be generated. +The procedure accepts multiple text lines. EXAMPLE display message -mtype +Warning "Save first your job"* The argument manager is checking if the last +provided argument is *-help* and generates the requested help message if this is +the case. So, also the following example will print the help message: + +__display message -mtype Info "It is 7:00" -help__ On the other hand, the +following call will result in an error: + + __display message -help -mtype Info "It is 7:00"__ + +*-> display message: Argument '-help' not known* + +## Interactive Procedure Call + +If Tk has been loaded a procedure can be called with the *-interactive* flag to +open a graphical form that allows specifying interactively all procedure +arguments. The following example assures that the Tk library is loaded and shows +the command line to call interactively the procedure declared in [PROCEDURE +CALLS](#section6): + + package require Tk + +__display message -interactive__ Also the *-interactive* flag has to be placed +at the last argument position as this is also required for the *-help* flag. +Arguments defined before the *-interactive* flag will be ignored. The following +example is therefore also a valid interactive procedure call: + + __display message__ -mtype Info "It is 7:00" + +__-interactive__ + +## Unnamed Arguments + +Unnamed arguments are typically provided to the called procedure as simple +parameters. This procedure calling form requires that the provided arguments are +strictly following the order of the specified arguments. Several parameters can +be assigned to the last argument if this one has the *-multiple* attribute. So, +the following declared procedure ... + + tepam::procedure {display_message} { + -args { + {mtype -choices {Info Warning Error}} + {text -type string -multiple} + } + } { + puts "$mtype: [join $text]" + } + +... can for example be called in the following ways: + + __display_message Info "It is PM 7:00."__ + *-> Info: It is PM 7:00.* + + __display_message Info "It is PM 7:00." "You should go home."__ + +*-> Info: It is PM 7:00. You should go home.* The nice thing is that unnamed +arguments can also be called as named arguments, which can be handy, for example +if the exact specified argument order is not known to a user: + + __display_message -mtype Info -text "It is PM 7:00."__ + *-> Info: It is PM 7:00.* + + __display_message -text "It is PM 7:00." -mtype Info__ + *-> Info: It is PM 7:00.* + + __display_message -mtype Info -text "It is PM 7:00." -text "You should go home."__ + *-> Info: It is PM 7:00. You should go home.* + + __display_message -text "It is PM 7:00." -text "You should go home." -mtype Info__ + +*-> Info: It is PM 7:00. You should go home.* + +## Named Arguments + +Named arguments have to be provided to a procedure in form of a parameter pairs +composed by the argument names and the argument values. The order how they are +provided during a procedure call is irrelevant and has not to match with the +argument specification order. + +The following declared procedure ... + + tepam::procedure {display_message} { + -args { + {-mtype -choices {Info Warning Error}} + {-text -type string -multiple} + } + } { + puts "$mtype: [join $text]" + } + +... can be called in the following ways: + + __display_message -mtype Info -text "It is PM 7:00."__ + *-> Info: It is PM 7:00.* + + __display_message -text "It is PM 7:00." -mtype Info__ + *-> Info: It is PM 7:00.* + + __display_message -mtype Info -text "It is PM 7:00." -text "You should go home."__ + *-> Info: It is PM 7:00. You should go home.* + + __display_message -text "It is PM 7:00." -text "You should go home." -mtype Info__ + +*-> Info: It is PM 7:00. You should go home.* Also named arguments that have not +the *-multiple* attribute can be provided multiple times. Only the last provided +argument will be retained in such a case: + + __display_message -mtype Info -text "It is PM 7:00." -mtype Warning__ + +*-> Warning: It is PM 7:00.* + +## Unnamed Arguments First, Named Arguments Later (Tk Style) + +A procedure that has been defined while the variable +__tepam::named_arguments_first__ was set to 1, or with the procedure attribute +*-named_arguments_first* set to 1 has to be called in the Tcl style. The +following procedure declaration will be used in this section to illustrate the +meaning of this calling style: + + __set tepam::named_arguments_first 1__ + tepam::procedure my_proc { + -args { + {-n1 -default ""} + {-n2 -default ""} + {u1 -default ""} + {u2 -default ""} + } + } { + puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'" + } + +The unnamed arguments are placed at the end of procedure call, after the named +arguments: + + my_proc __-n1 N1 -n2 N2 U1 U2__ + +*-> n1:'N1', n2:'N2', u1:'U1', u2:'U2'* The argument parser considers the first +argument that doesn't start with the '-' character as well as all following +arguments as unnamed argument: + + my_proc __U1 U2__ + +*-> n1:'', n2:'', u1:'U1', u2:'U2'* Named arguments can be defined multiple +times. If the named argument has the *-multiply* attribute, all argument values +will be collected in a list. Otherwise, only the last provided attribute value +will be retained: + + my_proc __-n1 N1 -n2 N2 -n1 M1 U1 U2__ + +*-> n1:'M1', n2:'N2', u1:'U1', u2:'U2'* The name of the first unnamed argument +has therefore not to start with the '-' character. The unnamed argument is +otherwise considered as name of another named argument. This is especially +important if the first unnamed argument is given by a variable that can contain +any character strings: + + my_proc __-n1 N1 -n2 N2 "->" "<-"__ + *-> my_proc: Argument '->' not known* + + set U1 "->" + my_proc __-n1 N1 -n2 N2 $U1 U2__ + my_proc: Argument '->' not known + +The '--' flag allows separating unambiguously the unnamed arguments from the +named arguments. All data after the '--' flag will be considered as unnamed +argument: + + my_proc __-n1 N1 -n2 N2 -- "->" "<-"__ + *-> n1:'N1', n2:'N2', u1:'->', u2:'<-'* + + set U1 "->" + my_proc __-n1 N1 -n2 N2 -- $U1 U2__ + +*-> n1:'N1', n2:'N2', u1:'->', u2:'<-'* + +## Named Arguments First, Unnamed Arguments Later (Tcl Style) + +The Tk calling style will be chosen if a procedure is defined while the variable +__tepam::named_arguments_first__ is set to 0, or if the procedure attribute +*-named_arguments_first* has been set to 0. The following procedure will be used +in this section to illustrate this calling style: + + __set tepam::named_arguments_first 0__ + tepam::procedure my_proc { + -args { + {-n1 -default ""} + {-n2 -default ""} + {u1} + {u2 -default "" -multiple} + } + } { + puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'" + } + +The unnamed arguments have to be provided first in this case. The named +arguments are provided afterwards: + + my_proc __U1 U2 -n1 N1 -n2 N2__ + +*-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'* The argument parser will assign to each +defined unnamed argument a value before it switches to read the named arguments. +This default behavior changes a bit if there are unnamed arguments that are +optional or that can take multiple values. + +An argument value will only be assigned to an unnamed argument that is optional +(that has either the *-optional* attribute or that has a default value), if the +value is not beginning with the '-' character or if no named arguments are +defined. The value that starts with '-' is otherwise considered as the name of a +named argument. + +Argument values are assigned to an argument that has the *-multiple* attribute +as long as the parameter value doesn't starts with the '-' character. + +Values that start with the '-' character can therefore not be assigned to +optional unnamed arguments, which restricts the usage of the Tcl procedure +calling style. The Tk style may be preferable in some cases, since it allows +separating unambiguously the named arguments from the unnamed ones with the '--' +flag. + +Let's explore in a bit less theoretically the ways how the previously defined +procedure can be called: The first example calls the procedure without any +parameters, which leads to an error since *u1* is a mandatory argument: + + my_proc + +*-> my_proc: Required argument is missing: u1* The procedure call is valid if +one parameter is provided for *u1*: + + my_proc __U1__ + +*-> n1:'', n2:'', u1:'U1', u2:''* If more parameters are provided that are not +starting with the '-' character, they will be attributed to the unnamed +arguments. *U2* will receive 3 of these parameters, since it accepts multiple +values: + + my_proc __U1 U2 U3 U4__ + +*-> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'* As soon as one parameter starts with +'-' and all unnamed arguments have been assigned, the argument manager tries to +interpret the parameter as name of a named argument. The procedure call will +fail if a value beginning with '-' is assigned to an unnamed argument: + + my_proc __U1 U2 U3 U4 -U5__ + +*-> my_proc: Argument '-U5' not known* The attribution of a parameter to a named +argument will fail if there are undefined unnamed (non optional) arguments. The +name specification will in this case simply be considered as a parameter value +that is attributed to the *next* unnamed argument. This was certainly not the +intention in the following example: + + my_proc __-n1 N1__ + +*-> n1:'', n2:'', u1:'-n1', u2:'N1'* The situation is completely different if +values have already been assigned to all mandatory unnamed arguments. A +parameter beginning with the '-' character will in this case be considered as a +name identifier for a named argument: + + my_proc __U1 -n1 N1__ + +*-> n1:'N1', n2:'', u1:'U1', u2:''* No unnamed arguments are allowed behind the +named arguments: + + my_proc __U1 -n1 N1 U2__ + +*-> my_proc: Argument 'U2' is not an option* The '--' flag has no special +meaning if not all mandatory arguments have got assigned a value. This flag will +simply be attributed to one of the unnamed arguments: + + my_proc __-- -n1 N1__ + +*-> n1:'N1', n2:'', u1:'--', u2:''* But the '--' flag is simply ignored if the +argument parser has started to handle the named arguments: + + my_proc __U1 -- -n1 N1__ + *-> n1:'N1', n2:'', u1:'U1', u2:''* + + my_proc __U1 -n1 N1 -- -n2 N2__ + +*-> n1:'N1', n2:'N2', u1:'U1', u2:''* + +## Raw Argument List + +It may be necessary sometimes that the procedure body is able to access the +entire list of arguments provided during a procedure call. This can happen via +the __args__ variable that contains always the unprocessed argument list: + + tepam::procedure {display_message} { + -args { + {-mtype -choices {Warning Error} -default Warning} + {text -type string -multiple} + + } + } { + puts "args: __$args__" + } + display_message -mtype Warning "It is 7:00" + +*-> args: -mtype Warning {It is 7:00}* + +# SEE ALSO + +[tepam(n)](tepam_introduction.md), +[tepam::argument_dialogbox(n)](tepam_argument_dialogbox.md) + +# KEYWORDS + +[argument integrity](../../../../index.md#argument_integrity), [argument +validation](../../../../index.md#argument_validation), +[arguments](../../../../index.md#arguments), +[procedure](../../../../index.md#procedure), +[subcommand](../../../../index.md#subcommand) + +# CATEGORY + +Procedures, arguments, parameters, options + +# COPYRIGHT + +Copyright © 2009-2013, Andreas Drollinger ADDED embedded/md/tcllib/files/modules/term/ansi_cattr.md Index: embedded/md/tcllib/files/modules/term/ansi_cattr.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/term/ansi_cattr.md @@ -0,0 +1,267 @@ + +[//000000001]: # (term::ansi::code::attr - Terminal control) +[//000000002]: # (Generated from file 'ansi_cattr.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (term::ansi::code::attr(n) 0.1 tcllib "Terminal control") + +# NAME + +term::ansi::code::attr - ANSI attribute sequences + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Introspection](#subsection1) + + - [Attributes](#subsection2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require term::ansi::code ?0.1? +package require term::ansi::code::attr ?0.1? + +[__::term::ansi::code::attr::names__](#1) +[__::term::ansi::code::attr::import__ ?*ns*? ?*arg*...?](#2) +[__::term::ansi::code::attr::fgblack__](#3) +[__::term::ansi::code::attr::fgred__](#4) +[__::term::ansi::code::attr::fggreen__](#5) +[__::term::ansi::code::attr::fgyellow__](#6) +[__::term::ansi::code::attr::fgblue__](#7) +[__::term::ansi::code::attr::fgmagenta__](#8) +[__::term::ansi::code::attr::fgcyan__](#9) +[__::term::ansi::code::attr::fgwhite__](#10) +[__::term::ansi::code::attr::fgdefault__](#11) +[__::term::ansi::code::attr::bgblack__](#12) +[__::term::ansi::code::attr::bgred__](#13) +[__::term::ansi::code::attr::bggreen__](#14) +[__::term::ansi::code::attr::bgyellow__](#15) +[__::term::ansi::code::attr::bgblue__](#16) +[__::term::ansi::code::attr::bgmagenta__](#17) +[__::term::ansi::code::attr::bgcyan__](#18) +[__::term::ansi::code::attr::bgwhite__](#19) +[__::term::ansi::code::attr::bgdefault__](#20) +[__::term::ansi::code::attr::bold__](#21) +[__::term::ansi::code::attr::dim__](#22) +[__::term::ansi::code::attr::italic__](#23) +[__::term::ansi::code::attr::underline__](#24) +[__::term::ansi::code::attr::blink__](#25) +[__::term::ansi::code::attr::revers__](#26) +[__::term::ansi::code::attr::hidden__](#27) +[__::term::ansi::code::attr::strike__](#28) +[__::term::ansi::code::attr::nobold__](#29) +[__::term::ansi::code::attr::noitalic__](#30) +[__::term::ansi::code::attr::nounderline__](#31) +[__::term::ansi::code::attr::noblink__](#32) +[__::term::ansi::code::attr::norevers__](#33) +[__::term::ansi::code::attr::nohidden__](#34) +[__::term::ansi::code::attr::nostrike__](#35) +[__::term::ansi::code::attr::reset__](#36) + +# DESCRIPTION + +This package provides symbolic names for the ANSI attribute control codes. For +each control code a single command is provided which returns this code as its +result. None of the commands of this package write to a channel; that is handled +by higher level packages, like __[term::ansi::send](ansi_send.md)__. + +# API + +## Introspection + + - __::term::ansi::code::attr::names__ + + This command is for introspection. It returns as its result a list + containing the names of all attribute commands. + + - __::term::ansi::code::attr::import__ ?*ns*? ?*arg*...? + + This command imports some or all attribute commands into the namespace *ns*. + This is by default the namespace *attr*. Note that this is relative + namespace name, placing the imported command into a child of the current + namespace. By default all commands are imported, this can howver be + restricted by listing the names of the wanted commands after the namespace + argument. + +## Attributes + + - __::term::ansi::code::attr::fgblack__ + + Set text color to *Black*. + + - __::term::ansi::code::attr::fgred__ + + Set text color to *Red*. + + - __::term::ansi::code::attr::fggreen__ + + Set text color to *Green*. + + - __::term::ansi::code::attr::fgyellow__ + + Set text color to *Yellow*. + + - __::term::ansi::code::attr::fgblue__ + + Set text color to *Blue*. + + - __::term::ansi::code::attr::fgmagenta__ + + Set text color to *Magenta*. + + - __::term::ansi::code::attr::fgcyan__ + + Set text color to *Cyan*. + + - __::term::ansi::code::attr::fgwhite__ + + Set text color to *White*. + + - __::term::ansi::code::attr::fgdefault__ + + Set default text color (*Black*). + + - __::term::ansi::code::attr::bgblack__ + + Set background to *Black*. + + - __::term::ansi::code::attr::bgred__ + + Set background to *Red*. + + - __::term::ansi::code::attr::bggreen__ + + Set background to *Green*. + + - __::term::ansi::code::attr::bgyellow__ + + Set background to *Yellow*. + + - __::term::ansi::code::attr::bgblue__ + + Set background to *Blue*. + + - __::term::ansi::code::attr::bgmagenta__ + + Set background to *Magenta*. + + - __::term::ansi::code::attr::bgcyan__ + + Set background to *Cyan*. + + - __::term::ansi::code::attr::bgwhite__ + + Set background to *White*. + + - __::term::ansi::code::attr::bgdefault__ + + Set default background (Transparent). + + - __::term::ansi::code::attr::bold__ + + Bold on. + + - __::term::ansi::code::attr::dim__ + + Dim on. + + - __::term::ansi::code::attr::italic__ + + Italics on. + + - __::term::ansi::code::attr::underline__ + + Underscore on. + + - __::term::ansi::code::attr::blink__ + + Blink on. + + - __::term::ansi::code::attr::revers__ + + Reverse on. + + - __::term::ansi::code::attr::hidden__ + + Hidden on. + + - __::term::ansi::code::attr::strike__ + + Strike-through on. + + - __::term::ansi::code::attr::nobold__ + + Bold off. + + - __::term::ansi::code::attr::noitalic__ + + Italics off. + + - __::term::ansi::code::attr::nounderline__ + + Underscore off. + + - __::term::ansi::code::attr::noblink__ + + Blink off. + + - __::term::ansi::code::attr::norevers__ + + Reverse off. + + - __::term::ansi::code::attr::nohidden__ + + Hidden off. + + - __::term::ansi::code::attr::nostrike__ + + Strike-through off. + + - __::term::ansi::code::attr::reset__ + + Reset all attributes to their default values. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *term* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[ansi](../../../../index.md#ansi), [attribute +control](../../../../index.md#attribute_control), [color +control](../../../../index.md#color_control), +[control](../../../../index.md#control), +[terminal](../../../../index.md#terminal) + +# CATEGORY + +Terminal control + +# COPYRIGHT + +Copyright © 2006 Andreas Kupries ADDED embedded/md/tcllib/files/modules/term/ansi_cctrl.md Index: embedded/md/tcllib/files/modules/term/ansi_cctrl.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/term/ansi_cctrl.md @@ -0,0 +1,560 @@ + +[//000000001]: # (term::ansi::code::ctrl - Terminal control) +[//000000002]: # (Generated from file 'ansi_cctrl.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (term::ansi::code::ctrl(n) 0.2 tcllib "Terminal control") + +# NAME + +term::ansi::code::ctrl - ANSI control sequences + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Introspection](#subsection1) + + - [Sequences](#subsection2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require term::ansi::code ?0.2? +package require term::ansi::code::ctrl ?0.2? + +[__::term::ansi::code::ctrl::names__](#1) +[__::term::ansi::code::ctrl::import__ ?*ns*? ?*arg*...?](#2) +[__::term::ansi::code::ctrl::eeol__](#3) +[__::term::ansi::code::ctrl::esol__](#4) +[__::term::ansi::code::ctrl::el__](#5) +[__::term::ansi::code::ctrl::ed__](#6) +[__::term::ansi::code::ctrl::eu__](#7) +[__::term::ansi::code::ctrl::es__](#8) +[__::term::ansi::code::ctrl::sd__](#9) +[__::term::ansi::code::ctrl::su__](#10) +[__::term::ansi::code::ctrl::ch__](#11) +[__::term::ansi::code::ctrl::sc__](#12) +[__::term::ansi::code::ctrl::rc__](#13) +[__::term::ansi::code::ctrl::sca__](#14) +[__::term::ansi::code::ctrl::rca__](#15) +[__::term::ansi::code::ctrl::st__](#16) +[__::term::ansi::code::ctrl::ct__](#17) +[__::term::ansi::code::ctrl::cat__](#18) +[__::term::ansi::code::ctrl::qdc__](#19) +[__::term::ansi::code::ctrl::qds__](#20) +[__::term::ansi::code::ctrl::qcp__](#21) +[__::term::ansi::code::ctrl::rd__](#22) +[__::term::ansi::code::ctrl::elw__](#23) +[__::term::ansi::code::ctrl::dlw__](#24) +[__::term::ansi::code::ctrl::eg__](#25) +[__::term::ansi::code::ctrl::lg__](#26) +[__::term::ansi::code::ctrl::scs0__ *tag*](#27) +[__::term::ansi::code::ctrl::scs1__ *tag*](#28) +[__::term::ansi::code::ctrl::sda__ *arg*...](#29) +[__::term::ansi::code::ctrl::sda_fgblack__](#30) +[__::term::ansi::code::ctrl::sda_fgred__](#31) +[__::term::ansi::code::ctrl::sda_fggreen__](#32) +[__::term::ansi::code::ctrl::sda_fgyellow__](#33) +[__::term::ansi::code::ctrl::sda_fgblue__](#34) +[__::term::ansi::code::ctrl::sda_fgmagenta__](#35) +[__::term::ansi::code::ctrl::sda_fgcyan__](#36) +[__::term::ansi::code::ctrl::sda_fgwhite__](#37) +[__::term::ansi::code::ctrl::sda_fgdefault__](#38) +[__::term::ansi::code::ctrl::sda_bgblack__](#39) +[__::term::ansi::code::ctrl::sda_bgred__](#40) +[__::term::ansi::code::ctrl::sda_bggreen__](#41) +[__::term::ansi::code::ctrl::sda_bgyellow__](#42) +[__::term::ansi::code::ctrl::sda_bgblue__](#43) +[__::term::ansi::code::ctrl::sda_bgmagenta__](#44) +[__::term::ansi::code::ctrl::sda_bgcyan__](#45) +[__::term::ansi::code::ctrl::sda_bgwhite__](#46) +[__::term::ansi::code::ctrl::sda_bgdefault__](#47) +[__::term::ansi::code::ctrl::sda_bold__](#48) +[__::term::ansi::code::ctrl::sda_dim__](#49) +[__::term::ansi::code::ctrl::sda_italic__](#50) +[__::term::ansi::code::ctrl::sda_underline__](#51) +[__::term::ansi::code::ctrl::sda_blink__](#52) +[__::term::ansi::code::ctrl::sda_revers__](#53) +[__::term::ansi::code::ctrl::sda_hidden__](#54) +[__::term::ansi::code::ctrl::sda_strike__](#55) +[__::term::ansi::code::ctrl::sda_nobold__](#56) +[__::term::ansi::code::ctrl::sda_noitalic__](#57) +[__::term::ansi::code::ctrl::sda_nounderline__](#58) +[__::term::ansi::code::ctrl::sda_noblink__](#59) +[__::term::ansi::code::ctrl::sda_norevers__](#60) +[__::term::ansi::code::ctrl::sda_nohidden__](#61) +[__::term::ansi::code::ctrl::sda_nostrike__](#62) +[__::term::ansi::code::ctrl::sda_reset__](#63) +[__::term::ansi::send::fcp__ *row* *col*](#64) +[__::term::ansi::code::ctrl::cu__ ?*n*?](#65) +[__::term::ansi::code::ctrl::cd__ ?*n*?](#66) +[__::term::ansi::code::ctrl::cf__ ?*n*?](#67) +[__::term::ansi::code::ctrl::cb__ ?*n*?](#68) +[__::term::ansi::code::ctrl::ss__ ?*s* *e*?](#69) +[__::term::ansi::code::ctrl::skd__ *code* *str*](#70) +[__::term::ansi::code::ctrl::title__ *str*](#71) +[__::term::ansi::code::ctrl::gron__](#72) +[__::term::ansi::code::ctrl::groff__](#73) +[__::term::ansi::code::ctrl::tlc__](#74) +[__::term::ansi::code::ctrl::trc__](#75) +[__::term::ansi::code::ctrl::brc__](#76) +[__::term::ansi::code::ctrl::blc__](#77) +[__::term::ansi::code::ctrl::ltj__](#78) +[__::term::ansi::code::ctrl::ttj__](#79) +[__::term::ansi::code::ctrl::rtj__](#80) +[__::term::ansi::code::ctrl::btj__](#81) +[__::term::ansi::code::ctrl::fwj__](#82) +[__::term::ansi::code::ctrl::hl__](#83) +[__::term::ansi::code::ctrl::vl__](#84) +[__::term::ansi::code::ctrl::groptim__ *str*](#85) +[__::term::ansi::code::ctrl::clear__](#86) +[__::term::ansi::code::ctrl::init__](#87) +[__::term::ansi::code::ctrl::showat__ *row* *col* *text*](#88) + +# DESCRIPTION + +This package provides symbolic names for the ANSI control sequences. For each +sequence a single command is provided which returns the sequence as its result. +None of the commands of this package write to a channel; that is handled by +higher level packages, like __[term::ansi::send](ansi_send.md)__. + +# API + +## Introspection + + - __::term::ansi::code::ctrl::names__ + + This command is for introspection. It returns as its result a list + containing the names of all attribute commands. + + - __::term::ansi::code::ctrl::import__ ?*ns*? ?*arg*...? + + This command imports some or all attribute commands into the namespace *ns*. + This is by default the namespace *ctrl*. Note that this is relative + namespace name, placing the imported command into a child of the current + namespace. By default all commands are imported, this can howver be + restricted by listing the names of the wanted commands after the namespace + argument. + +## Sequences + + - __::term::ansi::code::ctrl::eeol__ + + Erase (to) End Of Line + + - __::term::ansi::code::ctrl::esol__ + + Erase (to) Start Of Line + + - __::term::ansi::code::ctrl::el__ + + Erase (current) Line + + - __::term::ansi::code::ctrl::ed__ + + Erase Down (to bottom) + + - __::term::ansi::code::ctrl::eu__ + + Erase Up (to top) + + - __::term::ansi::code::ctrl::es__ + + Erase Screen + + - __::term::ansi::code::ctrl::sd__ + + Scroll Down + + - __::term::ansi::code::ctrl::su__ + + Scroll Up + + - __::term::ansi::code::ctrl::ch__ + + Cursor Home + + - __::term::ansi::code::ctrl::sc__ + + Save Cursor + + - __::term::ansi::code::ctrl::rc__ + + Restore Cursor (Unsave) + + - __::term::ansi::code::ctrl::sca__ + + Save Cursor + Attributes + + - __::term::ansi::code::ctrl::rca__ + + Restore Cursor + Attributes + + - __::term::ansi::code::ctrl::st__ + + Set Tab (@ current position) + + - __::term::ansi::code::ctrl::ct__ + + Clear Tab (@ current position) + + - __::term::ansi::code::ctrl::cat__ + + Clear All Tabs + + - __::term::ansi::code::ctrl::qdc__ + + Query Device Code + + - __::term::ansi::code::ctrl::qds__ + + Query Device Status + + - __::term::ansi::code::ctrl::qcp__ + + Query Cursor Position + + - __::term::ansi::code::ctrl::rd__ + + Reset Device + + - __::term::ansi::code::ctrl::elw__ + + Enable Line Wrap + + - __::term::ansi::code::ctrl::dlw__ + + Disable Line Wrap + + - __::term::ansi::code::ctrl::eg__ + + Enter Graphics Mode + + - __::term::ansi::code::ctrl::lg__ + + Exit Graphics Mode + + - __::term::ansi::code::ctrl::scs0__ *tag* + + Set default character set + + - __::term::ansi::code::ctrl::scs1__ *tag* + + Set alternate character set Select Character Set. + + Choose which character set is used for either default (scs0) or alternate + font (scs1). This does not change whether default or alternate font are + used, only their definition. + + The legal tags, and their meanings, are: + + * A + + United Kingdom Set + + * B + + ASCII Set + + * 0 + + Special Graphics + + * 1 + + Alternate Character ROM Standard Character Set + + * 2 + + Alternate Character ROM Special Graphics + + - __::term::ansi::code::ctrl::sda__ *arg*... + + Set Display Attributes. The arguments are the code sequences for the + possible attributes, as provided by the package + __[term::ansi::code::attr](ansi_cattr.md)__. For convenience this package + also provides additional commands each setting a single specific attribute. + + - __::term::ansi::code::ctrl::sda_fgblack__ + + Set text color to *Black*. + + - __::term::ansi::code::ctrl::sda_fgred__ + + Set text color to *Red*. + + - __::term::ansi::code::ctrl::sda_fggreen__ + + Set text color to *Green*. + + - __::term::ansi::code::ctrl::sda_fgyellow__ + + Set text color to *Yellow*. + + - __::term::ansi::code::ctrl::sda_fgblue__ + + Set text color to *Blue*. + + - __::term::ansi::code::ctrl::sda_fgmagenta__ + + Set text color to *Magenta*. + + - __::term::ansi::code::ctrl::sda_fgcyan__ + + Set text color to *Cyan*. + + - __::term::ansi::code::ctrl::sda_fgwhite__ + + Set text color to *White*. + + - __::term::ansi::code::ctrl::sda_fgdefault__ + + Set default text color (*Black*). + + - __::term::ansi::code::ctrl::sda_bgblack__ + + Set background to *Black*. + + - __::term::ansi::code::ctrl::sda_bgred__ + + Set background to *Red*. + + - __::term::ansi::code::ctrl::sda_bggreen__ + + Set background to *Green*. + + - __::term::ansi::code::ctrl::sda_bgyellow__ + + Set background to *Yellow*. + + - __::term::ansi::code::ctrl::sda_bgblue__ + + Set background to *Blue*. + + - __::term::ansi::code::ctrl::sda_bgmagenta__ + + Set background to *Magenta*. + + - __::term::ansi::code::ctrl::sda_bgcyan__ + + Set background to *Cyan*. + + - __::term::ansi::code::ctrl::sda_bgwhite__ + + Set background to *White*. + + - __::term::ansi::code::ctrl::sda_bgdefault__ + + Set default background (Transparent). + + - __::term::ansi::code::ctrl::sda_bold__ + + Bold on. + + - __::term::ansi::code::ctrl::sda_dim__ + + Dim on. + + - __::term::ansi::code::ctrl::sda_italic__ + + Italics on. + + - __::term::ansi::code::ctrl::sda_underline__ + + Underscore on. + + - __::term::ansi::code::ctrl::sda_blink__ + + Blink on. + + - __::term::ansi::code::ctrl::sda_revers__ + + Reverse on. + + - __::term::ansi::code::ctrl::sda_hidden__ + + Hidden on. + + - __::term::ansi::code::ctrl::sda_strike__ + + Strike-through on. + + - __::term::ansi::code::ctrl::sda_nobold__ + + Bold off. + + - __::term::ansi::code::ctrl::sda_noitalic__ + + Italics off. + + - __::term::ansi::code::ctrl::sda_nounderline__ + + Underscore off. + + - __::term::ansi::code::ctrl::sda_noblink__ + + Blink off. + + - __::term::ansi::code::ctrl::sda_norevers__ + + Reverse off. + + - __::term::ansi::code::ctrl::sda_nohidden__ + + Hidden off. + + - __::term::ansi::code::ctrl::sda_nostrike__ + + Strike-through off. + + - __::term::ansi::code::ctrl::sda_reset__ + + Reset all attributes to their default values. + + - __::term::ansi::send::fcp__ *row* *col* + + Force Cursor Position (aka Go To). + + - __::term::ansi::code::ctrl::cu__ ?*n*? + + Cursor Up. *n* defaults to 1. + + - __::term::ansi::code::ctrl::cd__ ?*n*? + + Cursor Down. *n* defaults to 1. + + - __::term::ansi::code::ctrl::cf__ ?*n*? + + Cursor Forward. *n* defaults to 1. + + - __::term::ansi::code::ctrl::cb__ ?*n*? + + Cursor Backward. *n* defaults to 1. + + - __::term::ansi::code::ctrl::ss__ ?*s* *e*? + + Scroll Screen (entire display, or between rows start end, inclusive). + + - __::term::ansi::code::ctrl::skd__ *code* *str* + + Set Key Definition. + + - __::term::ansi::code::ctrl::title__ *str* + + Set the terminal title. + + - __::term::ansi::code::ctrl::gron__ + + Switch to character/box graphics. I.e. switch to the alternate font. + + - __::term::ansi::code::ctrl::groff__ + + Switch to regular characters. I.e. switch to the default font. + + - __::term::ansi::code::ctrl::tlc__ + + Character graphics, Top Left Corner. + + - __::term::ansi::code::ctrl::trc__ + + Character graphics, Top Right Corner. + + - __::term::ansi::code::ctrl::brc__ + + Character graphics, Bottom Right Corner. + + - __::term::ansi::code::ctrl::blc__ + + Character graphics, Bottom Left Corner. + + - __::term::ansi::code::ctrl::ltj__ + + Character graphics, Left T Junction. + + - __::term::ansi::code::ctrl::ttj__ + + Character graphics, Top T Junction. + + - __::term::ansi::code::ctrl::rtj__ + + Character graphics, Right T Junction. + + - __::term::ansi::code::ctrl::btj__ + + Character graphics, Bottom T Junction. + + - __::term::ansi::code::ctrl::fwj__ + + Character graphics, Four-Way Junction. + + - __::term::ansi::code::ctrl::hl__ + + Character graphics, Horizontal Line. + + - __::term::ansi::code::ctrl::vl__ + + Character graphics, Vertical Line. + + - __::term::ansi::code::ctrl::groptim__ *str* + + Optimize character graphics. The generator commands above create way to many + superfluous commands shifting into and out of the graphics mode. This + command removes all shifts which are not needed. To this end it also knows + which characters will look the same in both modes, to handle strings created + outside of this package. + + - __::term::ansi::code::ctrl::clear__ + + Clear screen. In essence a sequence of CursorHome + EraseDown. + + - __::term::ansi::code::ctrl::init__ + + Initialize default and alternate fonts to ASCII and box graphics. + + - __::term::ansi::code::ctrl::showat__ *row* *col* *text* + + Format the block of text for display at the specified location. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *term* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[ansi](../../../../index.md#ansi), [attribute +control](../../../../index.md#attribute_control), [color +control](../../../../index.md#color_control), +[control](../../../../index.md#control), +[terminal](../../../../index.md#terminal) + +# CATEGORY + +Terminal control + +# COPYRIGHT + +Copyright © 2006-2008 Andreas Kupries ADDED embedded/md/tcllib/files/modules/term/ansi_cmacros.md Index: embedded/md/tcllib/files/modules/term/ansi_cmacros.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/term/ansi_cmacros.md @@ -0,0 +1,110 @@ + +[//000000001]: # (term::ansi::code::macros - Terminal control) +[//000000002]: # (Generated from file 'ansi_cmacros.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (term::ansi::code::macros(n) 0.1 tcllib "Terminal control") + +# NAME + +term::ansi::code::macros - Macro sequences + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Introspection](#subsection1) + + - [Sequences](#subsection2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require textutil::repeat +package require textutil::tabify +package require term::ansi::code::macros ?0.1? + +[__::term::ansi::code::macros::names__](#1) +[__::term::ansi::code::macros::import__ ?*ns*? ?*arg*...?](#2) +[__::term::ansi::code::macros::menu__ *menu*](#3) +[__::term::ansi::code::macros::frame__ *string*](#4) + +# DESCRIPTION + +This package provides higher level control sequences for more complex shapes. + +# API + +## Introspection + + - __::term::ansi::code::macros::names__ + + This command is for introspection. It returns as its result a list + containing the names of all attribute commands. + + - __::term::ansi::code::macros::import__ ?*ns*? ?*arg*...? + + This command imports some or all attribute commands into the namespace *ns*. + This is by default the namespace *macros*. Note that this is relative + namespace name, placing the imported command into a child of the current + namespace. By default all commands are imported, this can howver be + restricted by listing the names of the wanted commands after the namespace + argument. + +## Sequences + + - __::term::ansi::code::macros::menu__ *menu* + + The description of a menu is converted into a formatted rectangular block of + text, with the menu command characters highlighted using bold red text. The + result is returned as the result of the command. + + The description, *menu*, is a dictionary mapping from menu label to command + character. + + - __::term::ansi::code::macros::frame__ *string* + + The paragraph of text contained in the string is padded with spaces at the + right margin, after normalizing internal tabs, and then put into a frame + made of box-graphics. The result is returned as the result of the command. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *term* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[ansi](../../../../index.md#ansi), [control](../../../../index.md#control), +[frame](../../../../index.md#frame), [menu](../../../../index.md#menu), +[terminal](../../../../index.md#terminal) + +# CATEGORY + +Terminal control + +# COPYRIGHT + +Copyright © 2006 Andreas Kupries ADDED embedded/md/tcllib/files/modules/term/ansi_code.md Index: embedded/md/tcllib/files/modules/term/ansi_code.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/term/ansi_code.md @@ -0,0 +1,89 @@ + +[//000000001]: # (term::ansi::code - Terminal control) +[//000000002]: # (Generated from file 'ansi_code.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (term::ansi::code(n) 0.2 tcllib "Terminal control") + +# NAME + +term::ansi::code - Helper for control sequences + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require term::ansi::code ?0.2? + +[__::term::ansi::code::esc__ *str*](#1) +[__::term::ansi::code::escb__ *str*](#2) +[__::term::ansi::code::define__ *name* *escape* *code*](#3) +[__::term::ansi::code::const__ *name* *code*](#4) + +# DESCRIPTION + +This package provides commands enabling the definition of control sequences in +an easy manner. + + - __::term::ansi::code::esc__ *str* + + This command returns the argument string, prefixed with the ANSI escape + character, "\033." + + - __::term::ansi::code::escb__ *str* + + This command returns the argument string, prefixed with a common ANSI escape + sequence, "\033[". + + - __::term::ansi::code::define__ *name* *escape* *code* + + This command defines a procedure *name* which returns the control sequence + *code*, beginning with the specified escape sequence, either __esc__, or + __escb__. + + - __::term::ansi::code::const__ *name* *code* + + This command defines a procedure *name* which returns the control sequence + *code*. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *term* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[control](../../../../index.md#control), +[declare](../../../../index.md#declare), [define](../../../../index.md#define), +[terminal](../../../../index.md#terminal) + +# CATEGORY + +Terminal control + +# COPYRIGHT + +Copyright © 2006 Andreas Kupries ADDED embedded/md/tcllib/files/modules/term/ansi_ctrlu.md Index: embedded/md/tcllib/files/modules/term/ansi_ctrlu.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/term/ansi_ctrlu.md @@ -0,0 +1,123 @@ + +[//000000001]: # (term::ansi::ctrl::unix - Terminal control) +[//000000002]: # (Generated from file 'ansi_ctrlu.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (term::ansi::ctrl::unix(n) 0.1.1 tcllib "Terminal control") + +# NAME + +term::ansi::ctrl::unix - Control operations and queries + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Introspection](#subsection1) + + - [Operations](#subsection2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require term::ansi::ctrl::unix ?0.1.1? + +[__::term::ansi::ctrl::unix::import__ ?*ns*? ?*arg*...?](#1) +[__::term::ansi::ctrl::unix::raw__](#2) +[__::term::ansi::ctrl::unix::cooked__](#3) +[__::term::ansi::ctrl::unix::columns__](#4) +[__::term::ansi::ctrl::unix::rows__](#5) + +# DESCRIPTION + +*WARNING*: This package is unix-specific and depends on the availability of two +unix system commands for terminal control, i.e. __stty__ and __tput__, both of +which have to be found in the __$PATH__. If any of these two commands is missing +the loading of the package will fail. + +The package provides commands to switch the standard input of the current +process between *[raw](../../../../index.md#raw)* and +*[cooked](../../../../index.md#cooked)* input modes, and to query the size of +terminals, i.e. the available number of columns and lines. + +# API + +## Introspection + + - __::term::ansi::ctrl::unix::import__ ?*ns*? ?*arg*...? + + This command imports some or all attribute commands into the namespace *ns*. + This is by default the namespace *ctrl*. Note that this is relative + namespace name, placing the imported command into a child of the current + namespace. By default all commands are imported, this can howver be + restricted by listing the names of the wanted commands after the namespace + argument. + +## Operations + + - __::term::ansi::ctrl::unix::raw__ + + This command switches the standard input of the current process to + *[raw](../../../../index.md#raw)* input mode. This means that from then on + all characters typed by the user are immediately reported to the application + instead of waiting in the OS buffer until the Enter/Return key is received. + + - __::term::ansi::ctrl::unix::cooked__ + + This command switches the standard input of the current process to + *[cooked](../../../../index.md#cooked)* input mode. This means that from + then on all characters typed by the user are kept in OS buffers for editing + until the Enter/Return key is received. + + - __::term::ansi::ctrl::unix::columns__ + + This command queries the terminal connected to the standard input for the + number of columns available for display. + + - __::term::ansi::ctrl::unix::rows__ + + This command queries the terminal connected to the standard input for the + number of rows (aka lines) available for display. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *term* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[ansi](../../../../index.md#ansi), [columns](../../../../index.md#columns), +[control](../../../../index.md#control), [cooked](../../../../index.md#cooked), +[input mode](../../../../index.md#input_mode), +[lines](../../../../index.md#lines), [raw](../../../../index.md#raw), +[rows](../../../../index.md#rows), [terminal](../../../../index.md#terminal) + +# CATEGORY + +Terminal control + +# COPYRIGHT + +Copyright © 2006-2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/term/ansi_send.md Index: embedded/md/tcllib/files/modules/term/ansi_send.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/term/ansi_send.md @@ -0,0 +1,544 @@ + +[//000000001]: # (term::ansi::send - Terminal control) +[//000000002]: # (Generated from file 'ansi_send.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (term::ansi::send(n) 0.2 tcllib "Terminal control") + +# NAME + +term::ansi::send - Output of ANSI control sequences to terminals + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require term::ansi::send ?0.2? + +[__::term::ansi::send::import__ ?*ns*? *...*](#1) +[__::term::ansi::send::eeol__](#2) +[__::term::ansi::send::esol__](#3) +[__::term::ansi::send::el__](#4) +[__::term::ansi::send::ed__](#5) +[__::term::ansi::send::eu__](#6) +[__::term::ansi::send::es__](#7) +[__::term::ansi::send::sd__](#8) +[__::term::ansi::send::su__](#9) +[__::term::ansi::send::ch__](#10) +[__::term::ansi::send::sc__](#11) +[__::term::ansi::send::rc__](#12) +[__::term::ansi::send::sca__](#13) +[__::term::ansi::send::rca__](#14) +[__::term::ansi::send::st__](#15) +[__::term::ansi::send::ct__](#16) +[__::term::ansi::send::cat__](#17) +[__::term::ansi::send::qdc__](#18) +[__::term::ansi::send::qds__](#19) +[__::term::ansi::send::qcp__](#20) +[__::term::ansi::send::rd__](#21) +[__::term::ansi::send::elw__](#22) +[__::term::ansi::send::dlw__](#23) +[__::term::ansi::send::eg__](#24) +[__::term::ansi::send::lg__](#25) +[__::term::ansi::send::scs0__ *tag*](#26) +[__::term::ansi::send::scs1__ *tag*](#27) +[__::term::ansi::send::sda__ *arg*...](#28) +[__::term::ansi::send::sda_fgblack__](#29) +[__::term::ansi::send::sda_fgred__](#30) +[__::term::ansi::send::sda_fggreen__](#31) +[__::term::ansi::send::sda_fgyellow__](#32) +[__::term::ansi::send::sda_fgblue__](#33) +[__::term::ansi::send::sda_fgmagenta__](#34) +[__::term::ansi::send::sda_fgcyan__](#35) +[__::term::ansi::send::sda_fgwhite__](#36) +[__::term::ansi::send::sda_fgdefault__](#37) +[__::term::ansi::send::sda_bgblack__](#38) +[__::term::ansi::send::sda_bgred__](#39) +[__::term::ansi::send::sda_bggreen__](#40) +[__::term::ansi::send::sda_bgyellow__](#41) +[__::term::ansi::send::sda_bgblue__](#42) +[__::term::ansi::send::sda_bgmagenta__](#43) +[__::term::ansi::send::sda_bgcyan__](#44) +[__::term::ansi::send::sda_bgwhite__](#45) +[__::term::ansi::send::sda_bgdefault__](#46) +[__::term::ansi::send::sda_bold__](#47) +[__::term::ansi::send::sda_dim__](#48) +[__::term::ansi::send::sda_italic__](#49) +[__::term::ansi::send::sda_underline__](#50) +[__::term::ansi::send::sda_blink__](#51) +[__::term::ansi::send::sda_revers__](#52) +[__::term::ansi::send::sda_hidden__](#53) +[__::term::ansi::send::sda_strike__](#54) +[__::term::ansi::send::sda_nobold__](#55) +[__::term::ansi::send::sda_noitalic__](#56) +[__::term::ansi::send::sda_nounderline__](#57) +[__::term::ansi::send::sda_noblink__](#58) +[__::term::ansi::send::sda_norevers__](#59) +[__::term::ansi::send::sda_nohidden__](#60) +[__::term::ansi::send::sda_nostrike__](#61) +[__::term::ansi::send::sda_reset__](#62) +[__::term::ansi::send::fcp__ *row* *col*](#63) +[__::term::ansi::send::cu__ ?*n*?](#64) +[__::term::ansi::send::cd__ ?*n*?](#65) +[__::term::ansi::send::cf__ ?*n*?](#66) +[__::term::ansi::send::cb__ ?*n*?](#67) +[__::term::ansi::send::ss__ ?*s* *e*?](#68) +[__::term::ansi::send::skd__ *code* *str*](#69) +[__::term::ansi::send::title__ *str*](#70) +[__::term::ansi::send::gron__](#71) +[__::term::ansi::send::groff__](#72) +[__::term::ansi::send::tlc__](#73) +[__::term::ansi::send::trc__](#74) +[__::term::ansi::send::brc__](#75) +[__::term::ansi::send::blc__](#76) +[__::term::ansi::send::ltj__](#77) +[__::term::ansi::send::ttj__](#78) +[__::term::ansi::send::rtj__](#79) +[__::term::ansi::send::btj__](#80) +[__::term::ansi::send::fwj__](#81) +[__::term::ansi::send::hl__](#82) +[__::term::ansi::send::vl__](#83) +[__::term::ansi::send::groptim__ *str*](#84) +[__::term::ansi::send::clear__](#85) +[__::term::ansi::send::init__](#86) +[__::term::ansi::send::showat__ *row* *col* *text*](#87) + +# DESCRIPTION + +This package provides commands to send ANSI terminal control sequences to a +terminal. All commands come in two variants, one for sending to any channel, the +other for sending to *stdout*. + +The commands are defined using the control sequences provided by the package +__[term::ansi::code::ctrl](ansi_cctrl.md)__. They have the same arguments as the +commands they are based on, with the exception of the variant for sending to any +channel. Their first argument is always a channel handle, then followed by the +original arguments. Below we will list only the variant sending to *stdout*. + + - __::term::ansi::send::import__ ?*ns*? *...* + + Imports the commands of this package into the namespace *ns*. If not + specified it defaults to *send*. Note that this default is a relative + namespace name, i.e. the actual namespace will be created under the current + namespace. + + By default all commands will be imported, this can however be restricted to + specific commands, by listing them after the namespace to import them into. + + - __::term::ansi::send::eeol__ + + Erase (to) End Of Line. + + - __::term::ansi::send::esol__ + + Erase (to) Start Of Line. + + - __::term::ansi::send::el__ + + Erase (current) Line. + + - __::term::ansi::send::ed__ + + Erase Down (to bottom). + + - __::term::ansi::send::eu__ + + Erase Up (to top). + + - __::term::ansi::send::es__ + + Erase Screen. + + - __::term::ansi::send::sd__ + + Scroll Down. + + - __::term::ansi::send::su__ + + Scroll Up. + + - __::term::ansi::send::ch__ + + Cursor Home. + + - __::term::ansi::send::sc__ + + Save Cursor. Note: Only one saved position can be handled. This is no + unlimited stack. Saving before restoring will overwrite the saved data. + + - __::term::ansi::send::rc__ + + Restore Cursor (Unsave). + + - __::term::ansi::send::sca__ + + Save Cursor + Attributes. + + - __::term::ansi::send::rca__ + + Restore Cursor + Attributes. + + - __::term::ansi::send::st__ + + Set Tab (@ current position). + + - __::term::ansi::send::ct__ + + Clear Tab (@ current position). + + - __::term::ansi::send::cat__ + + Clear All Tabs. + + - __::term::ansi::send::qdc__ + + Query Device Code. + + - __::term::ansi::send::qds__ + + Query Device Status. + + - __::term::ansi::send::qcp__ + + Query Cursor Position. + + - __::term::ansi::send::rd__ + + Reset Device. + + - __::term::ansi::send::elw__ + + Enable Line Wrap. + + - __::term::ansi::send::dlw__ + + Disable Line Wrap. + + - __::term::ansi::send::eg__ + + Enter Graphics Mode. + + - __::term::ansi::send::lg__ + + Exit Graphics Mode. + + - __::term::ansi::send::scs0__ *tag* + + - __::term::ansi::send::scs1__ *tag* + + Select Character Set. + + Choose which character set is used for default (scs0) and alternate font + (scs1). This does not change whether default or alternate font are used, + just their definitions. + + The legal tags, and their meanings, are: + + * A + + United Kingdom Set + + * B + + ASCII Set + + * 0 + + Special Graphics + + * 1 + + Alternate Character ROM Standard Character Set + + * 2 + + Alternate Character ROM Special Graphics + + - __::term::ansi::send::sda__ *arg*... + + Set Display Attributes. The arguments are the code sequences for the + possible attributes, as provided by the package + __[term::ansi::code::attr](ansi_cattr.md)__. For convenience this package + also provides additional commands each setting a single specific attribute. + + - __::term::ansi::send::sda_fgblack__ + + Set text color to *Black*. + + - __::term::ansi::send::sda_fgred__ + + Set text color to *Red*. + + - __::term::ansi::send::sda_fggreen__ + + Set text color to *Green*. + + - __::term::ansi::send::sda_fgyellow__ + + Set text color to *Yellow*. + + - __::term::ansi::send::sda_fgblue__ + + Set text color to *Blue*. + + - __::term::ansi::send::sda_fgmagenta__ + + Set text color to *Magenta*. + + - __::term::ansi::send::sda_fgcyan__ + + Set text color to *Cyan*. + + - __::term::ansi::send::sda_fgwhite__ + + Set text color to *White*. + + - __::term::ansi::send::sda_fgdefault__ + + Set default text color (*Black*). + + - __::term::ansi::send::sda_bgblack__ + + Set background to *Black*. + + - __::term::ansi::send::sda_bgred__ + + Set background to *Red*. + + - __::term::ansi::send::sda_bggreen__ + + Set background to *Green*. + + - __::term::ansi::send::sda_bgyellow__ + + Set background to *Yellow*. + + - __::term::ansi::send::sda_bgblue__ + + Set background to *Blue*. + + - __::term::ansi::send::sda_bgmagenta__ + + Set background to *Magenta*. + + - __::term::ansi::send::sda_bgcyan__ + + Set background to *Cyan*. + + - __::term::ansi::send::sda_bgwhite__ + + Set background to *White*. + + - __::term::ansi::send::sda_bgdefault__ + + Set default background (Transparent). + + - __::term::ansi::send::sda_bold__ + + Bold on. + + - __::term::ansi::send::sda_dim__ + + Dim on. + + - __::term::ansi::send::sda_italic__ + + Italics on. + + - __::term::ansi::send::sda_underline__ + + Underscore on. + + - __::term::ansi::send::sda_blink__ + + Blink on. + + - __::term::ansi::send::sda_revers__ + + Reverse on. + + - __::term::ansi::send::sda_hidden__ + + Hidden on. + + - __::term::ansi::send::sda_strike__ + + Strike-through on. + + - __::term::ansi::send::sda_nobold__ + + Bold off. + + - __::term::ansi::send::sda_noitalic__ + + Italics off. + + - __::term::ansi::send::sda_nounderline__ + + Underscore off. + + - __::term::ansi::send::sda_noblink__ + + Blink off. + + - __::term::ansi::send::sda_norevers__ + + Reverse off. + + - __::term::ansi::send::sda_nohidden__ + + Hidden off. + + - __::term::ansi::send::sda_nostrike__ + + Strike-through off. + + - __::term::ansi::send::sda_reset__ + + Reset all attributes to their default values. + + - __::term::ansi::send::fcp__ *row* *col* + + Force Cursor Position (aka Go To). + + - __::term::ansi::send::cu__ ?*n*? + + Cursor Up. *n* defaults to 1. + + - __::term::ansi::send::cd__ ?*n*? + + Cursor Down. *n* defaults to 1. + + - __::term::ansi::send::cf__ ?*n*? + + Cursor Forward. *n* defaults to 1. + + - __::term::ansi::send::cb__ ?*n*? + + Cursor Backward. *n* defaults to 1. + + - __::term::ansi::send::ss__ ?*s* *e*? + + Scroll Screen (entire display, or between rows start end, inclusive). + + - __::term::ansi::send::skd__ *code* *str* + + Set Key Definition. + + - __::term::ansi::send::title__ *str* + + Set the terminal title. + + - __::term::ansi::send::gron__ + + Switch to character/box graphics. I.e. switch to the alternate font. + + - __::term::ansi::send::groff__ + + Switch to regular characters. I.e. switch to the default font. + + - __::term::ansi::send::tlc__ + + Character graphics, Top Left Corner. + + - __::term::ansi::send::trc__ + + Character graphics, Top Right Corner. + + - __::term::ansi::send::brc__ + + Character graphics, Bottom Right Corner. + + - __::term::ansi::send::blc__ + + Character graphics, Bottom Left Corner. + + - __::term::ansi::send::ltj__ + + Character graphics, Left T Junction. + + - __::term::ansi::send::ttj__ + + Character graphics, Top T Junction. + + - __::term::ansi::send::rtj__ + + Character graphics, Right T Junction. + + - __::term::ansi::send::btj__ + + Character graphics, Bottom T Junction. + + - __::term::ansi::send::fwj__ + + Character graphics, Four-Way Junction. + + - __::term::ansi::send::hl__ + + Character graphics, Horizontal Line. + + - __::term::ansi::send::vl__ + + Character graphics, Vertical Line. + + - __::term::ansi::send::groptim__ *str* + + Optimize character graphics. The generator commands above create way to many + superfluous commands shifting into and out of the graphics mode. This + command removes all shifts which are not needed. To this end it also knows + which characters will look the same in both modes, to handle strings created + outside of this package. + + - __::term::ansi::send::clear__ + + Clear screen. In essence a sequence of CursorHome + EraseDown. + + - __::term::ansi::send::init__ + + Initialize default and alternate fonts to ASCII and box graphics. + + - __::term::ansi::send::showat__ *row* *col* *text* + + Show the block of text at the specified location. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *term* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[character output](../../../../index.md#character_output), +[control](../../../../index.md#control), +[terminal](../../../../index.md#terminal) + +# CATEGORY + +Terminal control + +# COPYRIGHT + +Copyright © 2006 Andreas Kupries ADDED embedded/md/tcllib/files/modules/term/imenu.md Index: embedded/md/tcllib/files/modules/term/imenu.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/term/imenu.md @@ -0,0 +1,197 @@ + +[//000000001]: # (term::interact::menu - Terminal control) +[//000000002]: # (Generated from file 'imenu.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (term::interact::menu(n) 0.1 tcllib "Terminal control") + +# NAME + +term::interact::menu - Terminal widget, menu + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Class API](#section2) + + - [Object API](#section3) + + - [Configuration](#section4) + + - [Interaction](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require term::interact::menu ?0.1? + +[__term::interact::menu__ *object* *dict* ?*options*...?](#1) +[*object* __interact__](#2) +[*object* __done__](#3) +[*object* __clear__](#4) +[*object* __configure__](#5) +[*object* __configure__ *option*](#6) +[*object* __configure__ *option* *value*...](#7) +[*object* __cget__ *option*](#8) + +# DESCRIPTION + +This package provides a class for the creation of a simple menu control. + +# Class API + +The package exports a single command, the class command, enabling the creation +of menu instances. Its API is: + + - __term::interact::menu__ *object* *dict* ?*options*...? + + This command creates a new menu object with the name *object*, initializes + it, and returns the fully qualified name of the object command as its + result. + + The argument is the menu to show, possibly followed by configuration options + and their values. The options are explained in the section + [Configuration](#section4). The menu is a dictionary maping labels to + symbolic action codes. + +# Object API + +The objects created by the class command provide the methods listed below: + + - *object* __interact__ + + Shows the menu in the screen at the configured location and starts + interacting with it. This opens its own event loop for the processing of + incoming characters. The method returns when the interaction has completed. + See section [Interaction](#section5) for a description of the possible + interaction. + + The method returns the symbolic action of the menu item selected by the user + at the end of the interaction. + + - *object* __done__ + + This method can be used by user supplied actions to terminate the + interaction with the object. + + - *object* __clear__ + + This method can be used by user supplied actions to remove the menu from the + terminal. + + - *object* __configure__ + + - *object* __configure__ *option* + + - *object* __configure__ *option* *value*... + + - *object* __cget__ *option* + + Standard methods to retrieve and configure the options of the menu. + +# Configuration + +A menu instance recognizes the following options: + + - __-in__ chan + + Specifies the channel to read character sequences from. Defaults to + __stdin__. + + - __-out__ chan + + Specifies the channel to write the menu contents to. Defaults to __stdout__. + + - __-column__ int + + Specifies the column of the terminal where the left margin of the menu + display should appear. Defaults to 0, i.e. the left-most column. + + - __-line__ int + + Specifies the line of the terminal where the top margin of the menu display + should appear. Defaults to 0, i.e. the top-most line. + + - __-height__ int + + Specifies the number of lines of text to show at most in the display. + Defaults to 25. + + - __-actions__ dict + + Specifies a dictionary containing additional actions, using character + sequences as keys. Note that these sequences cannot override the hardwired + sequences described in section [Interaction](#section5). + + - __-hilitleft__ int + + - __-hilitright__ int + + By default the entire selected menu entry is highlighted in revers output. + However, when present these two options restrict revers dispay to the + specified sub-range of the entry. + + - __-framed__ bool + + By default the menu is shown using only header and footer out of characters + box graphics. If this flag is set the menu is fully enclosed in a box. + +# Interaction + +A menu object recognizes the control sequences listed below and acts as +described. The user can supply more control sequences to act on via the +configuration, but is not able to overide these defaults. + + - Cursor Up + + The selection is moved up one entry, except if the first entry of the menu + is already selected. + + - Cursor Down + + The selection is moved down one entry, except if the last entry of the menu + is already selected. + + - Enter/Return + + The interaction with the object is terminated. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *term* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[control](../../../../index.md#control), [menu](../../../../index.md#menu), +[terminal](../../../../index.md#terminal), [text +display](../../../../index.md#text_display) + +# CATEGORY + +Terminal control + +# COPYRIGHT + +Copyright © 2006 Andreas Kupries ADDED embedded/md/tcllib/files/modules/term/ipager.md Index: embedded/md/tcllib/files/modules/term/ipager.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/term/ipager.md @@ -0,0 +1,199 @@ + +[//000000001]: # (term::interact::pager - Terminal control) +[//000000002]: # (Generated from file 'ipager.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (term::interact::pager(n) 0.1 tcllib "Terminal control") + +# NAME + +term::interact::pager - Terminal widget, paging + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Class API](#section2) + + - [Object API](#section3) + + - [Configuration](#section4) + + - [Interaction](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require term::interact::pager ?0.1? + +[__term::interact::pager__ *object* *text* ?*options*...?](#1) +[*object* __interact__](#2) +[*object* __done__](#3) +[*object* __clear__](#4) +[*object* __text__ *text*](#5) +[*object* __configure__](#6) +[*object* __configure__ *option*](#7) +[*object* __configure__ *option* *value*...](#8) +[*object* __cget__ *option*](#9) + +# DESCRIPTION + +This package provides a class for the creation of a simple paging text display. + +# Class API + +The package exports a single command, the class command, enabling the creation +of pager instances. Its API is: + + - __term::interact::pager__ *object* *text* ?*options*...? + + This command creates a new pager object with the name *object*, initializes + it, and returns the fully qualified name of the object command as its + result. + + The argument is the text to show, possibly followed by configuration options + and their values. The options are explained in the section + [Configuration](#section4). + +# Object API + +The objects created by the class command provide the methods listed below: + + - *object* __interact__ + + Show the pager in the screen at the configured location and start + interacting with it. This opens its own event loop for the processing of + incoming characters. The method returns when the interaction has completed. + See section [Interaction](#section5) for a description of the possible + interaction. + + - *object* __done__ + + This method can be used by user supplied actions to terminate the + interaction with the object. + + - *object* __clear__ + + This method can be used by user supplied actions to remove the pager from + the terminal. + + - *object* __text__ *text* + + This method can be used to change the text shown by the pager. The pager + will reset the dispay to show the first line of the text at the top. + + - *object* __configure__ + + - *object* __configure__ *option* + + - *object* __configure__ *option* *value*... + + - *object* __cget__ *option* + + Standard methods to retrieve and configure the options of the pager. + +# Configuration + +A pager instance recognizes the following options: + + - __-in__ chan + + Specifies the channel to read character sequences from. Defaults to + __stdin__. + + - __-out__ chan + + Specifies the channel to write the pager contents to. Defaults to + __stdout__. + + - __-column__ int + + Specifies the column of the terminal where the left margin of the pager + display should appear. Defaults to 0, i.e. the left-most column. + + - __-line__ int + + Specifies the line of the terminal where the top margin of the pager display + should appear. Defaults to 0, i.e. the top-most line. + + - __-height__ int + + Specifies the number of lines of text to show at most in the display. + Defaults to 25. + + - __-actions__ dict + + Specifies a dictionary containing additional actions, using character + sequences as keys. Note that these sequences cannot override the hardwired + sequences described in section [Interaction](#section5). + +# Interaction + +A pager object recognizes the control sequences listed below and acts as +described. The user can supply more control sequences to act on via the +configuration, but is not able to overide these defaults. + + - Cursor Up + + The text is scrolled down a single line, making one more line visible at the + top. The pager will not react if the first line of the text is already + shown. + + - Cursor Down + + The text is scrolled up a single line, making one more line visible at the + bottom. The pager will not react if the last line of the text is already + shown. + + - Page Up + + The text is scrolled down a page. The pager will not react if the first line + of the text is already shown. + + - Page Down + + The text is scrolled up a page. The pager will not react if the last line of + the text is already shown. + + - Enter/Return + + The interaction with the object is terminated. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *term* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[control](../../../../index.md#control), [pager](../../../../index.md#pager), +[terminal](../../../../index.md#terminal), [text +display](../../../../index.md#text_display) + +# CATEGORY + +Terminal control + +# COPYRIGHT + +Copyright © 2006 Andreas Kupries ADDED embedded/md/tcllib/files/modules/term/receive.md Index: embedded/md/tcllib/files/modules/term/receive.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/term/receive.md @@ -0,0 +1,111 @@ + +[//000000001]: # (term::receive - Terminal control) +[//000000002]: # (Generated from file 'receive.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (term::receive(n) 0.1 tcllib "Terminal control") + +# NAME + +term::receive - General input from terminals + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require term::receive ?0.1? + +[__::term::receive::getch__ ?*chan*?](#1) +[__::term::receive::listen__ *cmd* ?*chan*?](#2) +[*cmd* __process__ *string*](#3) +[*cmd* __eof__](#4) +[__::term::receive::unlisten__ ?*chan*?](#5) + +# DESCRIPTION + +This package provides the most primitive commands for receiving characters to a +terminal. They are in essence convenient wrappers around the builtin commands +__[read](../../../../index.md#read)__ and __fileevent__. + + - __::term::receive::getch__ ?*chan*? + + This command reads a single character from the channel with handle *chan* + and returns it as the result of the command. + + If not specified *chan* defaults to __stdin__. + + It is the responsibility of the caller to make sure that the channel can + provide single characters. On unix this can be done, for example, by using + the command of package __[term::ansi::ctrl::unix](ansi_ctrlu.md)__. + + - __::term::receive::listen__ *cmd* ?*chan*? + + This command sets up a filevent listener for the channel with handle *chan* + and invokes the command prefix *cmd* whenever characters have been received, + or EOF was reached. + + If not specified *chan* defaults to __stdin__. + + The signature of the command prefix is + + * *cmd* __process__ *string* + + This method is invoked when characters were received, and *string* holds + them for processing. + + * *cmd* __eof__ + + This method is invoked when EOF was reached on the channel we listen on. + It will be the last call to be received by the callback. + + - __::term::receive::unlisten__ ?*chan*? + + This command disables the filevent listener for the channel with handle + *chan*. + + If not specified *chan* defaults to __stdin__. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *term* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[character input](../../../../index.md#character_input), +[control](../../../../index.md#control), [get +character](../../../../index.md#get_character), +[listener](../../../../index.md#listener), +[receiver](../../../../index.md#receiver), +[terminal](../../../../index.md#terminal) + +# CATEGORY + +Terminal control + +# COPYRIGHT + +Copyright © 2006 Andreas Kupries ADDED embedded/md/tcllib/files/modules/term/term.md Index: embedded/md/tcllib/files/modules/term/term.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/term/term.md @@ -0,0 +1,64 @@ + +[//000000001]: # (term - Terminal control) +[//000000002]: # (Generated from file 'term.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (term(n) 0.1 tcllib "Terminal control") + +# NAME + +term - General terminal control + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require term ?0.1? + +# DESCRIPTION + +It is planned to have this package provide highlevel general terminal control +commands, in the vein of ncurses or similar packages. Currently nothing has been +implemented however. I.e. this package is empty. It can be loaded, yet provides +nothing. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *term* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[control](../../../../index.md#control), +[terminal](../../../../index.md#terminal) + +# CATEGORY + +Terminal control + +# COPYRIGHT + +Copyright © 2006 Andreas Kupries ADDED embedded/md/tcllib/files/modules/term/term_bind.md Index: embedded/md/tcllib/files/modules/term/term_bind.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/term/term_bind.md @@ -0,0 +1,159 @@ + +[//000000001]: # (term::receive::bind - Terminal control) +[//000000002]: # (Generated from file 'term_bind.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (term::receive::bind(n) 0.1 tcllib "Terminal control") + +# NAME + +term::receive::bind - Keyboard dispatch from terminals + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Class API](#section2) + + - [Object API](#section3) + + - [Notes](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require term::receive::bind ?0.1? + +[__term::receive::bind__ *object* ?*map*?](#1) +[*object* __map__ *str* *cmd*](#2) +[*object* __default__ *cmd*](#3) +[*object* __listen__ ?*chan*?](#4) +[*object* __unlisten__ ?*chan*?](#5) +[*object* __reset__](#6) +[*object* __next__ *char*](#7) +[*object* __process__ *str*](#8) +[*object* __eof__](#9) + +# DESCRIPTION + +This package provides a class for the creation of simple dispatchers from +character sequences to actions. Internally each dispatcher is in essence a +deterministic finite automaton with tree structure. + +# Class API + +The package exports a single command, the class command, enabling the creation +of dispatcher instances. Its API is: + + - __term::receive::bind__ *object* ?*map*? + + This command creates a new dispatcher object with the name *object*, + initializes it, and returns the fully qualified name of the object command + as its result. + + The argument is a dictionary mapping from strings, i.e. character sequences + to the command prefices to invoke when the sequence is found in the input + stream. + +# Object API + +The objects created by the class command provide the methods listed below: + + - *object* __map__ *str* *cmd* + + This method adds an additional mapping from the string *str* to the action + *cmd*. The mapping will take effect immediately should the processor be in a + prefix of *str*, or at the next reset operation. The action is a command + prefix and will be invoked with one argument appended to it, the character + sequence causing the invokation. It is executed in the global namespace. + + - *object* __default__ *cmd* + + This method defines a default action *cmd* which will be invoked whenever an + unknown character sequence is encountered. The command prefix is handled in + the same as the regular action defined via method __map__. + + - *object* __listen__ ?*chan*? + + This methods sets up a filevent listener for the channel with handle *chan* + and invokes the dispatcher object whenever characters have been received, or + EOF was reached. + + If not specified *chan* defaults to __stdin__. + + - *object* __unlisten__ ?*chan*? + + This methods removes the filevent listener for the channel with handle + *chan*. + + If not specified *chan* defaults to __stdin__. + + - *object* __reset__ + + This method resets the character processor to the beginning of the tree. + + - *object* __next__ *char* + + This method causes the character processor to process the character *c*. + This may simply advance the internal state, or invoke an associated action + for a recognized sequence. + + - *object* __process__ *str* + + This method causes the character processor to process the character sequence + *str*, advancing the internal state and invoking action as necessary. This + is a callback for __listen__. + + - *object* __eof__ + + This method causes the character processor to handle EOF on the input. This + is currently no-op. This is a callback for __listen__. + +# Notes + +The simplicity of the DFA means that it is not possible to recognize a character +sequence with has a another recognized character sequence as its prefix. + +In other words, the set of recognized strings has to form a *prefix code*. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *term* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[character input](../../../../index.md#character_input), +[control](../../../../index.md#control), +[dispatcher](../../../../index.md#dispatcher), +[listener](../../../../index.md#listener), +[receiver](../../../../index.md#receiver), +[terminal](../../../../index.md#terminal) + +# CATEGORY + +Terminal control + +# COPYRIGHT + +Copyright © 2006 Andreas Kupries ADDED embedded/md/tcllib/files/modules/term/term_send.md Index: embedded/md/tcllib/files/modules/term/term_send.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/term/term_send.md @@ -0,0 +1,79 @@ + +[//000000001]: # (term::send - Terminal control) +[//000000002]: # (Generated from file 'term_send.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (term::send(n) 0.1 tcllib "Terminal control") + +# NAME + +term::send - General output to terminals + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require term::send ?0.1? + +[__::term::send::wrch__ *chan* *str*](#1) +[__::term::send::wr__ *str*](#2) + +# DESCRIPTION + +This package provides the most primitive commands for sending characters to a +terminal. They are in essence convenient wrappers around the builtin command +__puts__. + + - __::term::send::wrch__ *chan* *str* + + Send the text *str* to the channel specified by the handle *chan*. In + contrast to the builtin command __puts__ this command does not terminate the + string with a line terminator. It also forces an flush of Tcl internal and + OS buffers to ensure that the characters are processed immediately. + + - __::term::send::wr__ *str* + + This convenience command is like __::term::send::wrch__, except that the + destination channel is fixed to *stdout*. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *term* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[character output](../../../../index.md#character_output), +[control](../../../../index.md#control), +[terminal](../../../../index.md#terminal) + +# CATEGORY + +Terminal control + +# COPYRIGHT + +Copyright © 2006 Andreas Kupries ADDED embedded/md/tcllib/files/modules/textutil/adjust.md Index: embedded/md/tcllib/files/modules/textutil/adjust.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/textutil/adjust.md @@ -0,0 +1,213 @@ + +[//000000001]: # (textutil::adjust - Text and string utilities, macro processing) +[//000000002]: # (Generated from file 'adjust.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (textutil::adjust(n) 0.7.3 tcllib "Text and string utilities, macro processing") + +# NAME + +textutil::adjust - Procedures to adjust, indent, and undent paragraphs + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.2 +package require textutil::adjust ?0.7.3? + +[__::textutil::adjust::adjust__ *string* ?*option value...*?](#1) +[__::textutil::adjust::readPatterns__ *filename*](#2) +[__::textutil::adjust::listPredefined__](#3) +[__::textutil::adjust::getPredefined__ *filename*](#4) +[__::textutil::adjust::indent__ *string* *prefix* ?*skip*?](#5) +[__::textutil::adjust::undent__ *string*](#6) + +# DESCRIPTION + +The package __textutil::adjust__ provides commands that manipulate strings or +texts (a.k.a. long strings or string with embedded newlines or paragraphs), +adjusting, or indenting them. + +The complete set of procedures is described below. + + - __::textutil::adjust::adjust__ *string* ?*option value...*? + + Do a justification on the *string* according to the options. The string is + taken as one big paragraph, ignoring any newlines. Then the line is + formatted according to the options used, and the command returns a new + string with enough lines to contain all the printable chars in the input + string. A line is a set of characters between the beginning of the string + and a newline, or between 2 newlines, or between a newline and the end of + the string. If the input string is small enough, the returned string won't + contain any newlines. + + Together with __::textutil::adjust::indent__ it is possible to create + properly wrapped paragraphs with arbitrary indentations. + + By default, any occurrence of space or tabulation characters are replaced by + a single space so that each word in a line is separated from the next one by + exactly one space character, and this forms a *real* line. Each *real* line + is placed in a *logical* line, which has exactly a given length (see the + option __-length__ below). The *real* line may be shorter. Again by default, + trailing spaces are ignored before returning the string (see the option + __-full__ below). + + The following options may be used after the *string* parameter, and change + the way the command places a *real* line in a *logical* line. + + * __-full__ *boolean* + + If set to __false__ (default), trailing space characters are deleted + before returning the string. If set to __true__, any trailing space + characters are left in the string. + + * __-hyphenate__ *boolean* + + If set to __false__ (default), no hyphenation will be done. If set to + __true__, the command will try to hyphenate the last word of a line. + *Note*: Hyphenation patterns must be loaded prior, using the command + __::textutil::adjust::readPatterns__. + + * __-justify__ __center|left|plain|right__ + + Sets the justification of the returned string to either __left__ + (default), __center__, __plain__ or __right__. The justification means + that any line in the returned string but the last one is build according + to the value. If the justification is set to __plain__ and the number of + printable chars in the last line is less than 90% of the length of a + line (see the option __-length__), then this line is justified with the + __left__ value, avoiding the expansion of this line when it is too + small. The meaning of each value is: + + + __center__ + + The real line is centered in the logical line. If needed, a set of + space characters are added at the beginning (half of the needed set) + and at the end (half of the needed set) of the line if required (see + the option __-full__). + + + __left__ + + The real line is set on the left of the logical line. It means that + there are no space chars at the beginning of this line. If required, + all needed space chars are added at the end of the line (see the + option __-full__). + + + __plain__ + + The real line is exactly set in the logical line. It means that + there are no leading or trailing space chars. All the needed space + chars are added in the *real* line, between 2 (or more) words. + + + __right__ + + The real line is set on the right of the logical line. It means that + there are no space chars at the end of this line, and there may be + some space chars at the beginning, despite of the __-full__ option. + + * __-length__ *integer* + + Set the length of the *logical* line in the string to *integer*. + *integer* must be a positive integer value. Defaults to __72__. + + * __-strictlength__ *boolean* + + If set to __false__ (default), a line can exceed the specified + __-length__ if a single word is longer than __-length__. If set to + __true__, words that are longer than __-length__ are split so that no + line exceeds the specified __-length__. + + - __::textutil::adjust::readPatterns__ *filename* + + Loads the internal storage for hyphenation patterns with the contents of the + file *filename*. This has to be done prior to calling command + __::textutil::adjust::adjust__ with "__-hyphenate__ __true__", or the + hyphenation process will not work correctly. + + The package comes with a number of predefined pattern files, and the command + __::textutil::adjust::listPredefined__ can be used to find out their names. + + - __::textutil::adjust::listPredefined__ + + This command returns a list containing the names of the hyphenation files + coming with this package. + + - __::textutil::adjust::getPredefined__ *filename* + + Use this command to query the package for the full path name of the + hyphenation file *filename* coming with the package. Only the filenames + found in the list returned by __::textutil::adjust::listPredefined__ are + legal arguments for this command. + + - __::textutil::adjust::indent__ *string* *prefix* ?*skip*? + + Each line in the *string* is indented by adding the string *prefix* at its + beginning. The modified string is returned as the result of the command. + + If *skip* is specified the first *skip* lines are left untouched. The + default for *skip* is __0__, causing the modification of all lines. Negative + values for *skip* are treated like __0__. In other words, *skip* > __0__ + creates a hanging indentation. + + Together with __::textutil::adjust::adjust__ it is possible to create + properly wrapped paragraphs with arbitrary indentations. + + - __::textutil::adjust::undent__ *string* + + The command computes the common prefix for all lines in *string* consisting + solely out of whitespace, removes this from each line and returns the + modified string. + + Lines containing only whitespace are always reduced to completely empty + lines. They and empty lines are also ignored when computing the prefix to + remove. + + Together with __::textutil::adjust::adjust__ it is possible to create + properly wrapped paragraphs with arbitrary indentations. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *textutil* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +regexp(n), split(n), string(n) + +# KEYWORDS + +[TeX](../../../../index.md#tex), [adjusting](../../../../index.md#adjusting), +[formatting](../../../../index.md#formatting), +[hyphenation](../../../../index.md#hyphenation), +[indenting](../../../../index.md#indenting), +[justification](../../../../index.md#justification), +[paragraph](../../../../index.md#paragraph), +[string](../../../../index.md#string), +[undenting](../../../../index.md#undenting) + +# CATEGORY + +Text processing ADDED embedded/md/tcllib/files/modules/textutil/expander.md Index: embedded/md/tcllib/files/modules/textutil/expander.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/textutil/expander.md @@ -0,0 +1,474 @@ + +[//000000001]: # (textutil::expander - Text and string utilities, macro processing) +[//000000002]: # (Generated from file 'expander.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (textutil::expander(n) 1.3.1 tcllib "Text and string utilities, macro processing") + +# NAME + +textutil::expander - Procedures to process templates and expand text. + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [EXPANDER API](#section2) + + - [TUTORIAL](#section3) + + - [Basics](#subsection1) + + - [Embedding Macros](#subsection2) + + - [Writing Macro Commands](#subsection3) + + - [Changing the Expansion Brackets](#subsection4) + + - [Customized Macro Expansion](#subsection5) + + - [Using the Context Stack](#subsection6) + + - [HISTORY](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require textutil::expander ?1.3.1? + +[__::textutil::expander__ *expanderName*](#1) +[*expanderName* __cappend__ *text*](#2) +[*expanderName* __cget__ *varname*](#3) +[*expanderName* __cis__ *cname*](#4) +[*expanderName* __cname__](#5) +[*expanderName* __cpop__ *cname*](#6) +[*expanderName* __ctopandclear__](#7) +[*expanderName* __cpush__ *cname*](#8) +[*expanderName* __cset__ *varname* *value*](#9) +[*expanderName* __cvar__ *varname*](#10) +[*expanderName* __errmode__ *newErrmode*](#11) +[*expanderName* __evalcmd__ ?*newEvalCmd*?](#12) +[*expanderName* __expand__ *string* ?*brackets*?](#13) +[*expanderName* __lb__ ?*newbracket*?](#14) +[*expanderName* __rb__ ?*newbracket*?](#15) +[*expanderName* __reset__](#16) +[*expanderName* __setbrackets__ *lbrack rbrack*](#17) +[*expanderName* __textcmd__ ?*newTextCmd*?](#18) +[*expanderName* __where__](#19) + +# DESCRIPTION + +The Tcl __[subst](../../../../index.md#subst)__ command is often used to support +a kind of template processing. Given a string with embedded variables or +function calls, __[subst](../../../../index.md#subst)__ will interpolate the +variable and function values, returning the new string: + + % set greeting "Howdy" + Howdy + % proc place {} {return "World"} + % subst {$greeting, [place]!} + Howdy, World! + % + +By defining a suitable set of Tcl commands, +__[subst](../../../../index.md#subst)__ can be used to implement a markup +language similar to HTML. + +The __[subst](../../../../index.md#subst)__ command is efficient, but it has +three drawbacks for this kind of template processing: + + - There's no way to identify and process the plain text between two embedded + Tcl commands; that makes it difficult to handle plain text in a + context-sensitive way. + + - Embedded commands are necessarily bracketed by __[__ and __]__; it's + convenient to be able to choose different brackets in special cases. Someone + producing web pages that include a large quantity of Tcl code examples might + easily prefer to use __<<__ and __>>__ as the embedded code delimiters + instead. + + - There's no easy way to handle incremental input, as one might wish to do + when reading data from a socket. + +At present, expander solves the first two problems; eventually it will solve the +third problem as well. + +The following section describes the command API to the expander; this is +followed by the tutorial sections, see [TUTORIAL](#section3). + +# EXPANDER API + +The __textutil::expander__ package provides only one command, described below. +The rest of the section is taken by a description of the methods for the +expander objects created by this command. + + - __::textutil::expander__ *expanderName* + + The command creates a new expander object with an associated Tcl command + whose name is *expanderName*. This command may be used to invoke various + operations on the graph. If the *expanderName* is not fully qualified it is + interpreted as relative to the current namespace. The command has the + following general form: + + *expanderName* option ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. + +The following commands are possible for expander objects: + + - *expanderName* __cappend__ *text* + + Appends a string to the output in the current context. This command should + rarely be used by macros or application code. + + - *expanderName* __cget__ *varname* + + Retrieves the value of variable *varname*, defined in the current context. + + - *expanderName* __cis__ *cname* + + Determines whether or not the name of the current context is *cname*. + + - *expanderName* __cname__ + + Returns the name of the current context. + + - *expanderName* __cpop__ *cname* + + Pops a context from the context stack, returning all accumulated output in + that context. The context must be named *cname*, or an error results. + + - *expanderName* __ctopandclear__ + + Returns the output currently captured in the topmost context and clears that + buffer. This is similar to a combination of __cpop__ followed by __cpush__, + except that internal state (brackets) is preserved here. + + - *expanderName* __cpush__ *cname* + + Pushes a context named *cname* onto the context stack. The context must be + popped by __cpop__ before expansion ends or an error results. + + - *expanderName* __cset__ *varname* *value* + + Sets variable *varname* to *value* in the current context. + + - *expanderName* __cvar__ *varname* + + Retrieves the internal variable name of context variable *varname*; this + allows the variable to be passed to commands like __lappend__. + + - *expanderName* __errmode__ *newErrmode* + + Sets the macro expansion error mode to one of __nothing__, __macro__, + __error__, or __fail__; the default value is __fail__. The value determines + what the expander does if an error is detected during expansion of a macro. + + * __fail__ + + The error propagates normally and can be caught or ignored by the + application. + + * __error__ + + The macro expands into a detailed error message, and expansion + continues. + + * __macro__ + + The macro expands to itself; that is, it is passed along to the output + unchanged. + + * __nothing__ + + The macro expands to the empty string, and is effectively ignored. + + - *expanderName* __evalcmd__ ?*newEvalCmd*? + + Returns the current evaluation command, which defaults to __uplevel #0__. If + specified, *newEvalCmd* will be saved for future use and then returned; it + must be a Tcl command expecting one additional argument: the macro to + evaluate. + + - *expanderName* __expand__ *string* ?*brackets*? + + Expands the input string, replacing embedded macros with their expanded + values, and returns the expanded string. + + Note that this method pushes a new (empty) context on the stack of contexts + while it is running, and removes it on return. + + If *brackets* is given, it must be a list of two strings; the items will be + used as the left and right macro expansion bracket sequences for this + expansion only. + + - *expanderName* __lb__ ?*newbracket*? + + Returns the current value of the left macro expansion bracket; this is for + use as or within a macro, when the bracket needs to be included in the + output text. If *newbracket* is specified, it becomes the new bracket, and + is returned. + + - *expanderName* __rb__ ?*newbracket*? + + Returns the current value of the right macro expansion bracket; this is for + use as or within a macro, when the bracket needs to be included in the + output text. If *newbracket* is specified, it becomes the new bracket, and + is returned. + + - *expanderName* __reset__ + + Resets all expander settings to their initial values. Unusual results are + likely if this command is called from within a call to __expand__. + + - *expanderName* __setbrackets__ *lbrack rbrack* + + Sets the left and right macro expansion brackets. This command is for use as + or within a macro, or to permanently change the bracket definitions. By + default, the brackets are __[__ and __]__, but any non-empty string can be + used; for example, __<__ and __>__ or __(*__ and __*)__ or even __Hello,__ + and __World!__. + + - *expanderName* __textcmd__ ?*newTextCmd*? + + Returns the current command for processing plain text, which defaults to the + empty string, meaning *identity*. If specified, *newTextCmd* will be saved + for future use and then returned; it must be a Tcl command expecting one + additional argument: the text to process. The expander object will this + command for all plain text it encounters, giving the user of the object the + ability to process all plain text in some standard way before writing it to + the output. The object expects that the command returns the processed plain + text. + + *Note* that the combination of "__textcmd__ *plaintext*" is run through the + *evalcmd* for the actual evaluation. In other words, the *textcmd* is + treated as a special macro implicitly surrounding all plain text in the + template. + + - *expanderName* __where__ + + Returns a three-element list containing the current character position, + line, and column the expander is at in the processing of the current input + string. + +# TUTORIAL + +## Basics + +To begin, create an expander object: + + % package require textutil::expander + 1.2 + % ::textutil::expander myexp + ::myexp + % + +The created __::myexp__ object can be used to expand text strings containing +embedded Tcl commands. By default, embedded commands are delimited by square +brackets. Note that expander doesn't attempt to interpolate variables, since +variables can be referenced by embedded commands: + + % set greeting "Howdy" + Howdy + % proc place {} {return "World"} + % ::myexp expand {[set greeting], [place]!} + Howdy, World! + % + +## Embedding Macros + +An expander macro is simply a Tcl script embedded within a text string. Expander +evaluates the script in the global context, and replaces it with its result +string. For example, + + % set greetings {Howdy Hi "What's up"} + Howdy Hi "What's up" + % ::myexp expand {There are many ways to say "Hello, World!": + [set result {} + foreach greeting $greetings { + append result "$greeting, World!\\n" + } + set result] + And that's just a small sample!} + There are many ways to say "Hello, World!": + Howdy, World! + Hi, World! + What's up, World! + + And that's just a small sample! + % + +## Writing Macro Commands + +More typically, *macro commands* are used to create a markup language. A macro +command is just a Tcl command that returns an output string. For example, expand +can be used to implement a generic document markup language that can be +retargeted to HTML or any other output format: + + % proc bold {} {return ""} + % proc /bold {} {return ""} + % ::myexp expand {Some of this text is in [bold]boldface[/bold]} + Some of this text is in boldface + % + +The above definitions of __bold__ and __/bold__ returns HTML, but such commands +can be as complicated as needed; they could, for example, decide what to return +based on the desired output format. + +## Changing the Expansion Brackets + +By default, embedded macros are enclosed in square brackets, __[__ and __]__. If +square brackets need to be included in the output, the input can contain the +__lb__ and __rb__ commands. Alternatively, or if square brackets are +objectionable for some other reason, the macro expansion brackets can be changed +to any pair of non-empty strings. + +The __setbrackets__ command changes the brackets permanently. For example, you +can write pseudo-html by change them to __<__ and __>__: + + % ::myexp setbrackets < > + % ::myexp expand {This is boldface} + This is boldface + +Alternatively, you can change the expansion brackets temporarily by passing the +desired brackets to the __expand__ command: + + % ::myexp setbrackets "\\[" "\\]" + % ::myexp expand {This is boldface} {< >} + This is boldface + % + +## Customized Macro Expansion + +By default, macros are evaluated using the Tcl __uplevel #0__ command, so that +the embedded code executes in the global context. The application can provide a +different evaluation command using __evalcmd__; this allows the application to +use a safe interpreter, for example, or even to evaluated something other than +Tcl code. There is one caveat: to be recognized as valid, a macro must return 1 +when passed to Tcl's "info complete" command. + +For example, the following code "evaluates" each macro by returning the macro +text itself. + + proc identity {macro} {return $macro} + ::myexp evalcmd identity + +## Using the Context Stack + +Often it's desirable to define a pair of macros which operate in some way on the +plain text between them. Consider a set of macros for adding footnotes to a web +page: one could have implement something like this: + + Dr. Pangloss, however, thinks that this is the best of all + possible worlds.[footnote "See Candide, by Voltaire"] + +The __footnote__ macro would, presumably, assign a number to this footnote and +save the text to be formatted later on. However, this solution is ugly if the +footnote text is long or should contain additional markup. Consider the +following instead: + + Dr. Pangloss, however, thinks that this is the best of all + possible worlds.[footnote]See [bookTitle "Candide"], by + [authorsName "Voltaire"], for more information.[/footnote] + +Here the footnote text is contained between __footnote__ and __/footnote__ +macros, continues onto a second line, and contains several macros of its own. +This is both clearer and more flexible; however, with the features presented so +far there's no easy way to do it. That's the purpose of the context stack. + +All macro expansion takes place in a particular context. Here, the __footnote__ +macro pushes a new context onto the context stack. Then, all expanded text gets +placed in that new context. __/footnote__ retrieves it by popping the context. +Here's a skeleton implementation of these two macros: + + proc footnote {} { + ::myexp cpush footnote + } + + proc /footnote {} { + set footnoteText [::myexp cpop footnote] + + # Save the footnote text, and return an appropriate footnote + # number and link. + } + +The __cpush__ command pushes a new context onto the stack; the argument is the +context's name. It can be any string, but would typically be the name of the +macro itself. Then, __cpop__ verifies that the current context has the expected +name, pops it off of the stack, and returns the accumulated text. + +Expand provides several other tools related to the context stack. Suppose the +first macro in a context pair takes arguments or computes values which the +second macro in the pair needs. After calling __cpush__, the first macro can +define one or more context variables; the second macro can retrieve their values +any time before calling __cpop__. For example, suppose the document must specify +the footnote number explicitly: + + proc footnote {footnoteNumber} { + ::myexp cpush footnote + ::myexp csave num $footnoteNumber + # Return an appropriate link + } + + proc /footnote {} { + set footnoteNumber [::myexp cget num] + set footnoteText [::myexp cpop footnote] + + # Save the footnote text and its footnoteNumber for future + # output. + } + +At times, it might be desirable to define macros that are valid only within a +particular context pair; such macros should verify that they are only called +within the correct context using either __cis__ or __cname__. + +# HISTORY + +__expander__ was written by William H. Duquette; it is a repackaging of the +central algorithm of the expand macro processing tool. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *textutil* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[uri, http://www.wjduquette.com/expand, regexp, +[split](../../../../index.md#split), [string](../../../../index.md#string) + +# KEYWORDS + +[string](../../../../index.md#string), [template +processing](../../../../index.md#template_processing), [text +expansion](../../../../index.md#text_expansion) + +# CATEGORY + +Documentation tools + +# COPYRIGHT + +Copyright © William H. Duquette, http://www.wjduquette.com/expand ADDED embedded/md/tcllib/files/modules/textutil/repeat.md Index: embedded/md/tcllib/files/modules/textutil/repeat.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/textutil/repeat.md @@ -0,0 +1,82 @@ + +[//000000001]: # (textutil::repeat - Text and string utilities, macro processing) +[//000000002]: # (Generated from file 'repeat.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (textutil::repeat(n) 0.7.1 tcllib "Text and string utilities, macro processing") + +# NAME + +textutil::repeat - Procedures to repeat strings. + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.2 +package require textutil::repeat ?0.7? + +[__::textutil::repeat::strRepeat__ *text* *num*](#1) +[__::textutil::repeat::blank__ *num*](#2) + +# DESCRIPTION + +The package __textutil::repeat__ provides commands to generate long strings by +repeating a shorter string many times. + +The complete set of procedures is described below. + + - __::textutil::repeat::strRepeat__ *text* *num* + + This command returns a string containing the *text* repeated *num* times. + The repetitions are joined without characters between them. A value of *num* + <= 0 causes the command to return an empty string. + + *Note*: If the Tcl core the package is loaded in provides the command + __string repeat__ then this command will be implemented in its terms, for + maximum possible speed. Otherwise a fast implementation in Tcl will be used. + + - __::textutil::repeat::blank__ *num* + + A convenience command. Returns a string of *num* spaces. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *textutil* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +regexp(n), split(n), string(n) + +# KEYWORDS + +[blanks](../../../../index.md#blanks), +[repetition](../../../../index.md#repetition), +[string](../../../../index.md#string) + +# CATEGORY + +Text processing ADDED embedded/md/tcllib/files/modules/textutil/tabify.md Index: embedded/md/tcllib/files/modules/textutil/tabify.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/textutil/tabify.md @@ -0,0 +1,105 @@ + +[//000000001]: # (textutil::tabify - Text and string utilities, macro processing) +[//000000002]: # (Generated from file 'tabify.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (textutil::tabify(n) 0.7 tcllib "Text and string utilities, macro processing") + +# NAME + +textutil::tabify - Procedures to (un)tabify strings + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.2 +package require textutil::tabify ?0.7? + +[__::textutil::tabify::tabify__ *string* ?*num*?](#1) +[__::textutil::tabify::tabify2__ *string* ?*num*?](#2) +[__::textutil::tabify::untabify__ *string* ?*num*?](#3) +[__::textutil::tabify::untabify2__ *string* ?*num*?](#4) + +# DESCRIPTION + +The package __textutil::tabify__ provides commands that convert between +tabulation and ordinary whitespace in strings. + +The complete set of procedures is described below. + + - __::textutil::tabify::tabify__ *string* ?*num*? + + Tabify the *string* by replacing any substring of *num* space chars by a + tabulation and return the result as a new string. *num* defaults to 8. + + - __::textutil::tabify::tabify2__ *string* ?*num*? + + Similar to __::textutil::tabify__ this command tabifies the *string* and + returns the result as a new string. A different algorithm is used however. + Instead of replacing any substring of *num* spaces this command works more + like an editor. *num* defaults to 8. + + Each line of the text in *string* is treated as if there are tabstops every + *num* columns. Only sequences of space characters containing more than one + space character and found immediately before a tabstop are replaced with + tabs. + + - __::textutil::tabify::untabify__ *string* ?*num*? + + Untabify the *string* by replacing any tabulation char by a substring of + *num* space chars and return the result as a new string. *num* defaults to + 8. + + - __::textutil::tabify::untabify2__ *string* ?*num*? + + Untabify the *string* by replacing any tabulation char by a substring of at + most *num* space chars and return the result as a new string. Unlike + __textutil::tabify::untabify__ each tab is not replaced by a fixed number of + space characters. The command overlays each line in the *string* with + tabstops every *num* columns instead and replaces tabs with just enough + space characters to reach the next tabstop. This is the complement of the + actions taken by __::textutil::tabify::tabify2__. *num* defaults to 8. + + There is one asymmetry though: A tab can be replaced with a single space, + but not the other way around. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *textutil* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +regexp(n), split(n), string(n) + +# KEYWORDS + +[formatting](../../../../index.md#formatting), +[string](../../../../index.md#string), [tabstops](../../../../index.md#tabstops) + +# CATEGORY + +Text processing ADDED embedded/md/tcllib/files/modules/textutil/textutil.md Index: embedded/md/tcllib/files/modules/textutil/textutil.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/textutil/textutil.md @@ -0,0 +1,389 @@ + +[//000000001]: # (textutil - Text and string utilities, macro processing) +[//000000002]: # (Generated from file 'textutil.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (textutil(n) 0.8 tcllib "Text and string utilities, macro processing") + +# NAME + +textutil - Procedures to manipulate texts and strings. + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.2 +package require textutil ?0.8? + +[__::textutil::adjust__ *string args*](#1) +[__::textutil::adjust::readPatterns__ *filename*](#2) +[__::textutil::adjust::listPredefined__](#3) +[__::textutil::adjust::getPredefined__ *filename*](#4) +[__::textutil::indent__ *string* *prefix* ?*skip*?](#5) +[__::textutil::undent__ *string*](#6) +[__::textutil::splitn__ *string* ?*len*?](#7) +[__::textutil::splitx__ *string* ?*regexp*?](#8) +[__::textutil::tabify__ *string* ?*num*?](#9) +[__::textutil::tabify2__ *string* ?*num*?](#10) +[__::textutil::trim__ *string* ?*regexp*?](#11) +[__::textutil::trimleft__ *string* ?*regexp*?](#12) +[__::textutil::trimright__ *string* ?*regexp*?](#13) +[__::textutil::trimPrefix__ *string* *prefix*](#14) +[__::textutil::trimEmptyHeading__ *string*](#15) +[__::textutil::untabify__ *string* ?*num*?](#16) +[__::textutil::untabify2__ *string* ?*num*?](#17) +[__::textutil::strRepeat__ *text num*](#18) +[__::textutil::blank__ *num*](#19) +[__::textutil::chop__ *string*](#20) +[__::textutil::tail__ *string*](#21) +[__::textutil::cap__ *string*](#22) +[__::textutil::uncap__ *string*](#23) +[__::textutil::longestCommonPrefixList__ *list*](#24) +[__::textutil::longestCommonPrefix__ ?*string*...?](#25) + +# DESCRIPTION + +The package __textutil__ provides commands that manipulate strings or texts +(a.k.a. long strings or string with embedded newlines or paragraphs). It is +actually a bundle providing the commands of the six packages + + - __[textutil::adjust](adjust.md)__ + + - __[textutil::repeat](repeat.md)__ + + - __[textutil::split](textutil_split.md)__ + + - __[textutil::string](textutil_string.md)__ + + - __[textutil::tabify](tabify.md)__ + + - __[textutil::trim](trim.md)__ + +in the namespace __textutil__. + +The bundle is *deprecated*, and it will be removed in a future release of +Tcllib, after the next release. It is recommended to use the relevant sub +packages instead for whatever functionality is needed by the using package or +application. + +The complete set of procedures is described below. + + - __::textutil::adjust__ *string args* + + Do a justification on the *string* according to *args*. The string is taken + as one big paragraph, ignoring any newlines. Then the line is formatted + according to the options used, and the command return a new string with + enough lines to contain all the printable chars in the input string. A line + is a set of chars between the beginning of the string and a newline, or + between 2 newlines, or between a newline and the end of the string. If the + input string is small enough, the returned string won't contain any + newlines. + + Together with __::textutil::indent__ it is possible to create properly + wrapped paragraphs with arbitrary indentations. + + By default, any occurrence of spaces characters or tabulation are replaced + by a single space so each word in a line is separated from the next one by + exactly one space char, and this forms a *real* line. Each *real* line is + placed in a *logical* line, which have exactly a given length (see + __-length__ option below). The *real* line may have a lesser length. Again + by default, any trailing spaces are ignored before returning the string (see + __-full__ option below). The following options may be used after the + *string* parameter, and change the way the command place a *real* line in a + *logical* line. + + * -full *boolean* + + If set to __false__, any trailing space chars are deleted before + returning the string. If set to __true__, any trailing space chars are + left in the string. Default to __false__. + + * __-hyphenate__ *boolean* + + if set to __false__, no hyphenation will be done. If set to __true__, + the last word of a line is tried to be hyphenated. Defaults to + __false__. Note: hyphenation patterns must be loaded prior, using the + command __::textutil::adjust::readPatterns__. + + * __-justify__ __center|left|plain|right__ + + Set the justification of the returned string to __center__, __left__, + __plain__ or __right__. By default, it is set to __left__. The + justification means that any line in the returned string but the last + one is build according to the value. If the justification is set to + __plain__ and the number of printable chars in the last line is less + than 90% of the length of a line (see __-length__), then this line is + justified with the __left__ value, avoiding the expansion of this line + when it is too small. The meaning of each value is: + + + __center__ + + The real line is centered in the logical line. If needed, a set of + space characters are added at the beginning (half of the needed set) + and at the end (half of the needed set) of the line if required (see + the option __-full__). + + + __left__ + + The real line is set on the left of the logical line. It means that + there are no space chars at the beginning of this line. If required, + all needed space chars are added at the end of the line (see the + option __-full__). + + + __plain__ + + The real line is exactly set in the logical line. It means that + there are no leading or trailing space chars. All the needed space + chars are added in the *real* line, between 2 (or more) words. + + + __right__ + + The real line is set on the right of the logical line. It means that + there are no space chars at the end of this line, and there may be + some space chars at the beginning, despite of the __-full__ option. + + * __-length__ *integer* + + Set the length of the *logical* line in the string to *integer*. + *integer* must be a positive integer value. Defaults to __72__. + + * __-strictlength__ *boolean* + + If set to __false__, a line can exceed the specified __-length__ if a + single word is longer than __-length__. If set to __true__, words that + are longer than __-length__ are split so that no line exceeds the + specified __-length__. Defaults to __false__. + + - __::textutil::adjust::readPatterns__ *filename* + + Loads the internal storage for hyphenation patterns with the contents of the + file *filename*. This has to be done prior to calling command + __::textutil::adjust__ with "__-hyphenate__ __true__", or the hyphenation + process will not work correctly. + + The package comes with a number of predefined pattern files, and the command + __::textutil::adjust::listPredefined__ can be used to find out their names. + + - __::textutil::adjust::listPredefined__ + + This command returns a list containing the names of the hyphenation files + coming with this package. + + - __::textutil::adjust::getPredefined__ *filename* + + Use this command to query the package for the full path name of the + hyphenation file *filename* coming with the package. Only the filenames + found in the list returned by __::textutil::adjust::listPredefined__ are + legal arguments for this command. + + - __::textutil::indent__ *string* *prefix* ?*skip*? + + Each line in the *string* indented by adding the string *prefix* at its + beginning. The modified string is returned as the result of the command. + + If *skip* is specified the first *skip* lines are left untouched. The + default for *skip* is __0__, causing the modification of all lines. Negative + values for *skip* are treated like __0__. In other words, *skip* > __0__ + creates a hanging indentation. + + Together with __::textutil::adjust__ it is possible to create properly + wrapped paragraphs with arbitrary indentations. + + - __::textutil::undent__ *string* + + The command computes the common prefix for all lines in *string* consisting + solely out of whitespace, removes this from each line and returns the + modified string. + + Lines containing only whitespace are always reduced to completely empty + lines. They and empty lines are also ignored when computing the prefix to + remove. + + Together with __::textutil::adjust__ it is possible to create properly + wrapped paragraphs with arbitrary indentations. + + - __::textutil::splitn__ *string* ?*len*? + + This command splits the given *string* into chunks of *len* characters and + returns a list containing these chunks. The argument *len* defaults to __1__ + if none is specified. A negative length is not allowed and will cause the + command to throw an error. Providing an empty string as input is allowed, + the command will then return an empty list. If the length of the *string* is + not an entire multiple of the chunk length, then the last chunk in the + generated list will be shorter than *len*. + + - __::textutil::splitx__ *string* ?*regexp*? + + Split the *string* and return a list. The string is split according to the + regular expression *regexp* instead of a simple list of chars. Note that if + you add parenthesis into the *regexp*, the parentheses part of separator + would be added into list as additional element. If the *string* is empty the + result is the empty list, like for __[split](../../../../index.md#split)__. + If *regexp* is empty the *string* is split at every character, like + __[split](../../../../index.md#split)__ does. The regular expression + *regexp* defaults to "[\\t \\r\\n]+". + + - __::textutil::tabify__ *string* ?*num*? + + Tabify the *string* by replacing any substring of *num* space chars by a + tabulation and return the result as a new string. *num* defaults to 8. + + - __::textutil::tabify2__ *string* ?*num*? + + Similar to __::textutil::tabify__ this command tabifies the *string* and + returns the result as a new string. A different algorithm is used however. + Instead of replacing any substring of *num* spaces this command works more + like an editor. *num* defaults to 8. + + Each line of the text in *string* is treated as if there are tabstops every + *num* columns. Only sequences of space characters containing more than one + space character and found immediately before a tabstop are replaced with + tabs. + + - __::textutil::trim__ *string* ?*regexp*? + + Remove in *string* any leading and trailing substring according to the + regular expression *regexp* and return the result as a new string. This + apply on any *line* in the string, that is any substring between 2 newline + chars, or between the beginning of the string and a newline, or between a + newline and the end of the string, or, if the string contain no newline, + between the beginning and the end of the string. The regular expression + *regexp* defaults to "[ \\t]+". + + - __::textutil::trimleft__ *string* ?*regexp*? + + Remove in *string* any leading substring according to the regular expression + *regexp* and return the result as a new string. This apply on any *line* in + the string, that is any substring between 2 newline chars, or between the + beginning of the string and a newline, or between a newline and the end of + the string, or, if the string contain no newline, between the beginning and + the end of the string. The regular expression *regexp* defaults to "[ + \\t]+". + + - __::textutil::trimright__ *string* ?*regexp*? + + Remove in *string* any trailing substring according to the regular + expression *regexp* and return the result as a new string. This apply on any + *line* in the string, that is any substring between 2 newline chars, or + between the beginning of the string and a newline, or between a newline and + the end of the string, or, if the string contain no newline, between the + beginning and the end of the string. The regular expression *regexp* + defaults to "[ \\t]+". + + - __::textutil::trimPrefix__ *string* *prefix* + + Removes the *prefix* from the beginning of *string* and returns the result. + The *string* is left unchanged if it doesn't have *prefix* at its beginning. + + - __::textutil::trimEmptyHeading__ *string* + + Looks for empty lines (including lines consisting of only whitespace) at the + beginning of the *string* and removes it. The modified string is returned as + the result of the command. + + - __::textutil::untabify__ *string* ?*num*? + + Untabify the *string* by replacing any tabulation char by a substring of + *num* space chars and return the result as a new string. *num* defaults to + 8. + + - __::textutil::untabify2__ *string* ?*num*? + + Untabify the *string* by replacing any tabulation char by a substring of at + most *num* space chars and return the result as a new string. Unlike + __textutil::untabify__ each tab is not replaced by a fixed number of space + characters. The command overlays each line in the *string* with tabstops + every *num* columns instead and replaces tabs with just enough space + characters to reach the next tabstop. This is the complement of the actions + taken by __::textutil::tabify2__. *num* defaults to 8. + + There is one asymmetry though: A tab can be replaced with a single space, + but not the other way around. + + - __::textutil::strRepeat__ *text num* + + The implementation depends on the core executing the package. Used __string + repeat__ if it is present, or a fast tcl implementation if it is not. + Returns a string containing the *text* repeated *num* times. The repetitions + are joined without characters between them. A value of *num* <= 0 causes the + command to return an empty string. + + - __::textutil::blank__ *num* + + A convenience command. Returns a string of *num* spaces. + + - __::textutil::chop__ *string* + + A convenience command. Removes the last character of *string* and returns + the shortened string. + + - __::textutil::tail__ *string* + + A convenience command. Removes the first character of *string* and returns + the shortened string. + + - __::textutil::cap__ *string* + + Capitalizes the first character of *string* and returns the modified string. + + - __::textutil::uncap__ *string* + + The complementary operation to __::textutil::cap__. Forces the first + character of *string* to lower case and returns the modified string. + + - __::textutil::longestCommonPrefixList__ *list* + + - __::textutil::longestCommonPrefix__ ?*string*...? + + Computes the longest common prefix for either the *string*s given to the + command, or the strings specified in the single *list*, and returns it as + the result of the command. + + If no strings were specified the result is the empty string. If only one + string was specified, the string itself is returned, as it is its own + longest common prefix. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *textutil* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +regexp(n), split(n), string(n) + +# KEYWORDS + +[TeX](../../../../index.md#tex), [formatting](../../../../index.md#formatting), +[hyphenation](../../../../index.md#hyphenation), +[indenting](../../../../index.md#indenting), +[paragraph](../../../../index.md#paragraph), [regular +expression](../../../../index.md#regular_expression), +[string](../../../../index.md#string), [trimming](../../../../index.md#trimming) + +# CATEGORY + +Text processing ADDED embedded/md/tcllib/files/modules/textutil/textutil_split.md Index: embedded/md/tcllib/files/modules/textutil/textutil_split.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/textutil/textutil_split.md @@ -0,0 +1,88 @@ + +[//000000001]: # (textutil::split - Text and string utilities, macro processing) +[//000000002]: # (Generated from file 'textutil_split.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (textutil::split(n) 0.8 tcllib "Text and string utilities, macro processing") + +# NAME + +textutil::split - Procedures to split texts + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.2 +package require textutil::split ?0.8? + +[__::textutil::split::splitn__ *string* ?*len*?](#1) +[__::textutil::split::splitx__ *string* ?*regexp*?](#2) + +# DESCRIPTION + +The package __textutil::split__ provides commands that split strings by size and +arbitrary regular expressions. + +The complete set of procedures is described below. + + - __::textutil::split::splitn__ *string* ?*len*? + + This command splits the given *string* into chunks of *len* characters and + returns a list containing these chunks. The argument *len* defaults to __1__ + if none is specified. A negative length is not allowed and will cause the + command to throw an error. Providing an empty string as input is allowed, + the command will then return an empty list. If the length of the *string* is + not an entire multiple of the chunk length, then the last chunk in the + generated list will be shorter than *len*. + + - __::textutil::split::splitx__ *string* ?*regexp*? + + This command splits the *string* and return a list. The string is split + according to the regular expression *regexp* instead of a simple list of + chars. *Note*: When parentheses are used in the *regexp*, i.e. regex capture + groups, then these groups will be added into the result list as additional + elements. If the *string* is empty the result is the empty list, like for + __[split](../../../../index.md#split)__. If *regexp* is empty the *string* + is split at every character, like __[split](../../../../index.md#split)__ + does. The regular expression *regexp* defaults to "[\\t \\r\\n]+". + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *textutil* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +regexp(n), split(n), string(n) + +# KEYWORDS + +[regular expression](../../../../index.md#regular_expression), +[split](../../../../index.md#split), [string](../../../../index.md#string) + +# CATEGORY + +Text processing ADDED embedded/md/tcllib/files/modules/textutil/textutil_string.md Index: embedded/md/tcllib/files/modules/textutil/textutil_string.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/textutil/textutil_string.md @@ -0,0 +1,113 @@ + +[//000000001]: # (textutil::string - Text and string utilities, macro processing) +[//000000002]: # (Generated from file 'textutil_string.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (textutil::string(n) 0.8 tcllib "Text and string utilities, macro processing") + +# NAME + +textutil::string - Procedures to manipulate texts and strings. + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.2 +package require textutil::string ?0.8? + +[__::textutil::string::chop__ *string*](#1) +[__::textutil::string::tail__ *string*](#2) +[__::textutil::string::cap__ *string*](#3) +[__::textutil::string::capEachWord__ *string*](#4) +[__::textutil::string::uncap__ *string*](#5) +[__::textutil::string::longestCommonPrefixList__ *list*](#6) +[__::textutil::string::longestCommonPrefix__ ?*string*...?](#7) + +# DESCRIPTION + +The package __textutil::string__ provides miscellaneous string manipulation +commands. + +The complete set of procedures is described below. + + - __::textutil::string::chop__ *string* + + A convenience command. Removes the last character of *string* and returns + the shortened string. + + - __::textutil::string::tail__ *string* + + A convenience command. Removes the first character of *string* and returns + the shortened string. + + - __::textutil::string::cap__ *string* + + Capitalizes the first character of *string* and returns the modified string. + + - __::textutil::string::capEachWord__ *string* + + Capitalizes the first character of word of the *string* and returns the + modified string. Words quoted with either backslash or dollar-sign are left + untouched. + + - __::textutil::string::uncap__ *string* + + The complementary operation to __::textutil::string::cap__. Forces the first + character of *string* to lower case and returns the modified string. + + - __::textutil::string::longestCommonPrefixList__ *list* + + - __::textutil::string::longestCommonPrefix__ ?*string*...? + + Computes the longest common prefix for either the *string*s given to the + command, or the strings specified in the single *list*, and returns it as + the result of the command. + + If no strings were specified the result is the empty string. If only one + string was specified, the string itself is returned, as it is its own + longest common prefix. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *textutil* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +regexp(n), split(n), string(n) + +# KEYWORDS + +[capitalize](../../../../index.md#capitalize), +[chop](../../../../index.md#chop), [common +prefix](../../../../index.md#common_prefix), +[formatting](../../../../index.md#formatting), +[prefix](../../../../index.md#prefix), [string](../../../../index.md#string), +[uncapitalize](../../../../index.md#uncapitalize) + +# CATEGORY + +Text processing ADDED embedded/md/tcllib/files/modules/textutil/trim.md Index: embedded/md/tcllib/files/modules/textutil/trim.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/textutil/trim.md @@ -0,0 +1,112 @@ + +[//000000001]: # (textutil::trim - Text and string utilities, macro processing) +[//000000002]: # (Generated from file 'trim.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (textutil::trim(n) 0.7 tcllib "Text and string utilities, macro processing") + +# NAME + +textutil::trim - Procedures to trim strings + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.2 +package require textutil::trim ?0.7? + +[__::textutil::trim::trim__ *string* ?*regexp*?](#1) +[__::textutil::trim::trimleft__ *string* ?*regexp*?](#2) +[__::textutil::trim::trimright__ *string* ?*regexp*?](#3) +[__::textutil::trim::trimPrefix__ *string* *prefix*](#4) +[__::textutil::trim::trimEmptyHeading__ *string*](#5) + +# DESCRIPTION + +The package __textutil::trim__ provides commands that trim strings using +arbitrary regular expressions. + +The complete set of procedures is described below. + + - __::textutil::trim::trim__ *string* ?*regexp*? + + Remove in *string* any leading and trailing substring according to the + regular expression *regexp* and return the result as a new string. This is + done for all *lines* in the string, that is any substring between 2 newline + chars, or between the beginning of the string and a newline, or between a + newline and the end of the string, or, if the string contain no newline, + between the beginning and the end of the string. The regular expression + *regexp* defaults to "[ \\t]+". + + - __::textutil::trim::trimleft__ *string* ?*regexp*? + + Remove in *string* any leading substring according to the regular expression + *regexp* and return the result as a new string. This apply on any *line* in + the string, that is any substring between 2 newline chars, or between the + beginning of the string and a newline, or between a newline and the end of + the string, or, if the string contain no newline, between the beginning and + the end of the string. The regular expression *regexp* defaults to "[ + \\t]+". + + - __::textutil::trim::trimright__ *string* ?*regexp*? + + Remove in *string* any trailing substring according to the regular + expression *regexp* and return the result as a new string. This apply on any + *line* in the string, that is any substring between 2 newline chars, or + between the beginning of the string and a newline, or between a newline and + the end of the string, or, if the string contain no newline, between the + beginning and the end of the string. The regular expression *regexp* + defaults to "[ \\t]+". + + - __::textutil::trim::trimPrefix__ *string* *prefix* + + Removes the *prefix* from the beginning of *string* and returns the result. + The *string* is left unchanged if it doesn't have *prefix* at its beginning. + + - __::textutil::trim::trimEmptyHeading__ *string* + + Looks for empty lines (including lines consisting of only whitespace) at the + beginning of the *string* and removes it. The modified string is returned as + the result of the command. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *textutil* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +regexp(n), split(n), string(n) + +# KEYWORDS + +[prefix](../../../../index.md#prefix), [regular +expression](../../../../index.md#regular_expression), +[string](../../../../index.md#string), [trimming](../../../../index.md#trimming) + +# CATEGORY + +Text processing ADDED embedded/md/tcllib/files/modules/tie/tie.md Index: embedded/md/tcllib/files/modules/tie/tie.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/tie/tie.md @@ -0,0 +1,499 @@ + +[//000000001]: # (tie - Tcl Data Structures) +[//000000002]: # (Generated from file 'tie.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tie(n) 1.1 tcllib "Tcl Data Structures") + +# NAME + +tie - Array persistence + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [USING TIES](#section2) + + - [TIE API](#subsection1) + + - [STANDARD DATA SOURCE TYPES](#subsection2) + + - [CREATING NEW DATA SOURCES](#section3) + + - [DATA SOURCE OBJECTS](#subsection3) + + - [REGISTERING A NEW DATA SOURCE CLASS](#subsection4) + + - [DATA SOURCE CLASS](#subsection5) + + - [DATA SOURCE OBJECT API](#subsection6) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require tie ?1.1? + +[__::tie::tie__ *arrayvarname* *options*... *dstype* *dsname*...](#1) +[__::tie::untie__ *arrayvarname* ?*token*?](#2) +[__::tie::info__ __ties__ *arrayvarname*](#3) +[__::tie::info__ __types__](#4) +[__::tie::info__ __type__ *dstype*](#5) +[__::tie::register__ *dsclasscmd* __as__ *dstype*](#6) +[__dsclasscmd__ *objname* ?*dsname*...?](#7) +[__ds__ __destroy__](#8) +[__ds__ __names__](#9) +[__ds__ __size__](#10) +[__ds__ __get__](#11) +[__ds__ __set__ *dict*](#12) +[__ds__ __unset__ ?*pattern*?](#13) +[__ds__ __setv__ *index* *value*](#14) +[__ds__ __unsetv__ *index*](#15) +[__ds__ __getv__ *index*](#16) + +# DESCRIPTION + +The __tie__ package provides a framework for the creation of persistent Tcl +array variables. It should be noted that the provided mechanism is generic +enough to also allow its usage for the distribution of the contents of Tcl +arrays over multiple threads and processes, i.e. communication. + +This, persistence and communication, is accomplished by *tying*) a Tcl array +variable to a *[data source](../../../../index.md#data_source)*. Examples of +data sources are other Tcl arrays and files. + +It should be noted that a single Tcl array variable can be tied to more than one +*[data source](../../../../index.md#data_source)*. It is this feature which +allows the framework to be used for communication as well. Just tie several Tcl +arrays in many client processes to a Tcl array in a server and all changes to +any of them will be distributed to all. Less centralized variants of this are of +course possible as well. + +# USING TIES + +## TIE API + +This section describes the basic API used to establish and remove ties between +Tcl array variables and data sources. This interface is the only one a casual +user has to be concerned about. The following sections about the various +internal interfaces can be safely skipped. + + - __::tie::tie__ *arrayvarname* *options*... *dstype* *dsname*... + + This command establishes a tie between the Tcl array whose name is provided + by the argument *arrayvarname* and the *[data + source](../../../../index.md#data_source)* identified by the *dstype* and + its series of *dsname* arguments. All changes made to the Tcl array after + this command returns will be saved to the *[data + source](../../../../index.md#data_source)* for safekeeping (or + distribution). + + The result of the command is always a token which identifies the new tie. + This token can be used later to destroy this specific tie. + + * varname *arrayvarname* (in) + + The name of the Tcl array variable to connect the new tie to. + + * name|command *dstype* (in) + + This argument specifies the type of the *[data + source](../../../../index.md#data_source)* we wish to access. The + *dstype* can be one of __log__, __array__, __remotearray__, __file__, + __growfile__, or __dsource__; in addition, the programmer can register + additional data source types. Each *dstype* is followed by one or more + arguments that identify the *[data + source](../../../../index.md#data_source)* to which the array is to be + tied. + + * string *dsname* (in) + + The series of *dsname* arguments coming after the *dstype* identifies + the *[data source](../../../../index.md#data_source)* we wish to connect + to, and has to be appropriate for the chosen type. + + The command understands a number of additional options which guide the + process of setting up the connection between Tcl array and *[data + source](../../../../index.md#data_source)*. + + * __-open__ + + The Tcl array for the new tie is *loaded* from the *[data + source](../../../../index.md#data_source)*, and the previously existing + contents of the Tcl array are erased. Care is taken to *not* erase the + previous contents should the creation of the tie fail. + + This option and the option __-save__ exclude each other. If neither this + nor option __-save__ are specified then this option is assumed as + default. + + * __-save__ + + The Tcl array for the new tie is *saved* to the *[data + source](../../../../index.md#data_source)*, and the previously existing + contents of the *[data source](../../../../index.md#data_source)* are + erased. + + This option and the option __-open__ exclude each other. If neither this + nor option __-open__ are specified then option __-open__ is assumed as + default. + + * __-merge__ + + Using this option prevents the erasure of any previously existing + content and merges the data instead. It can be specified in conjunction + with either __-open__ or __-save__. They determine how data existing in + both Tcl array and *[data source](../../../../index.md#data_source)*, + i.e duplicates, are dealt with. + + When used with __-open__ data in the *[data + source](../../../../index.md#data_source)* has precedence. In other + words, for duplicates the data in the *[data + source](../../../../index.md#data_source)* is loaded into the Tcl array. + + When used with __-save__ data in the Tcl array has precedence. In other + words, for duplicates the data in the Tcl array is saved into the *[data + source](../../../../index.md#data_source)*. + + - __::tie::untie__ *arrayvarname* ?*token*? + + This command dissolves one or more ties associated with the Tcl array named + by *arrayvarname*. If no *token* is specified then all ties to that Tcl + array are dissolved. Otherwise only the tie the token stands for is removed, + if it is actually connected to the array. Trying to remove a specific tie + not belonging to the provided array will cause an error. + + It should be noted that while severing a tie will destroy management + information internal to the package the *[data + source](../../../../index.md#data_source)* which was handled by the tie will + not be touched, only closed. + + After the command returns none of changes made to the array will be saved to + the *[data source](../../../../index.md#data_source)* anymore. + + The result of the command is an empty string. + + * varname *arrayname* (in) + + The name of a Tcl array variable which may have ties. + + * handle *token* (in) + + A handle representing a specific tie. This argument is optional. + + - __::tie::info__ __ties__ *arrayvarname* + + This command returns a list of ties associated with the Tcl array variable + named by *arrayvarname*. The result list will be empty if the variable has + no ties associated with it. + + - __::tie::info__ __types__ + + This command returns a dictionary of registered types, and the class + commands they are associated with. + + - __::tie::info__ __type__ *dstype* + + This command returns the fully resolved class command for a type name. This + means that the command will follow a chain of type definitions ot its end. + +## STANDARD DATA SOURCE TYPES + +This package provides the six following types as examples and standard data +sources. + + - __log__ + + This *[data source](../../../../index.md#data_source)* does not maintain any + actual data, nor persistence. It does not accept any identifying arguments. + All changes are simply logged to __stdout__. + + - __array__ + + This *[data source](../../../../index.md#data_source)* uses a regular Tcl + array as the origin of the persistent data. It accepts a single identifying + argument, the name of this Tcl array. All changes are mirrored to that + array. + + - __remotearray__ + + This *[data source](../../../../index.md#data_source)* is similar to + __array__. The difference is that the Tcl array to which we are mirroring is + not directly accessible, but through a + __[send](../../../../index.md#send)__-like command. + + It accepts three identifying arguments, the name of the other Tcl array, the + command prefix for the __[send](../../../../index.md#send)__-like accessor + command, and an identifier for the remote entity hosting the array, in this + order. All changes are mirrored to that array, via the command prefix. All + commands will be executed in the context of the global namespace. + + __[send](../../../../index.md#send)__-like means that the command prefix has + to have __[send](../../../../index.md#send)__ syntax and semantics. I.e. it + is a channel over which we can send arbitrary commands to some other entity. + The remote array *[data source](../../../../index.md#data_source)* however + uses only the commands __[set](../../../../index.md#set)__, __unset__, + __array exists__, __array names__, __array set__, and __array get__ to + retrieve and set values in the remote array. + + The command prefix and the entity id are separate to allow the data source + to use options like __-async__ when assembling the actual commands. + + Examples of command prefixes, listed with the id of the remote entity, + without options. In reality only the part before the id is the command + prefix: + + * __[send](../../../../index.md#send)__ *tkname* + + The Tcl array is in a remote interpreter and is accessed via Tk's X + communication. + + * __comm::comm send__ *hostportid* + + The Tcl array is in a remote interpreter and is accessed through a + socket. + + * __thread::send__ *threadid* + + The Tcl array is in a remote interpreter in a different thread of this + process. + + - __file__ + + This *[data source](../../../../index.md#data_source)* uses a single file as + origin of the persistent data. It accepts a single identifying argument, the + path to this file. The file has to be both readable and writable. It may not + exist, the *[data source](../../../../index.md#data_source)* will create it + in that case. This (and only this) situation will require that the directory + for the file exists and is writable as well. + + All changes are saved in the file, as proper Tcl commands, one command per + operation. In other words, the file will always contain a proper Tcl script. + + If the file exists when the tie using it is set up, then it will be + compacted, i.e. superfluous operations are removed, if the operations log + stored in it contains either at least one operation clearing the whole + array, or at least 1.5 times more operations than entries in the loaded + array. + + - __growfile__ + + This *[data source](../../../../index.md#data_source)* is like __file__ in + terms of the storage medium for the array data, and how it is configured. In + constrast to the former it however assumes and ensures that the tied array + will never shrink. I.e. the creation of new array entries, and the + modification of existing entries is allowed, but the deletion of entries is + not, and causes the data source to throw errors. + + This restriction allows us to simplify both file format and access to the + file radically. For one, the file is read only once and the internal cache + cannot be invalidated. Second, writing data is reduced to a simple append, + and no compaction step is necessary. The format of the contents is the + string representation of a dictionary which can be incrementally extended + forever at the end. + + - __dsource__ + + This *[data source](../../../../index.md#data_source)* uses an explicitly + specified *data source object* as the source for the persistent data. It + accepts a single identifying argument, the command prefix, i.e. object + command. + + To use this type it is necessary to know how the framework manages ties and + what [data source objects](#subsection3) are. + + All changes are delegated to the specified object. + +# CREATING NEW DATA SOURCES + +This section is of no interest to the casual user of ties. Only developers +wishing to create new data sources have to know the information provided herein. + +## DATA SOURCE OBJECTS + +All ties are represented internally by an in-memory object which mediates +between the tie framework and the specific *[data +source](../../../../index.md#data_source)*, like an array, file, etc. This is +the *data source object*. + +Its class, the [data source class](#subsection5) is *not* generic, but specific +to the type of the *[data source](../../../../index.md#data_source)*. Writing a +new *[data source](../../../../index.md#data_source)* requires us to write such +a class, and then registering it with the framework as a new type. + +The following subsections describe the various APIs a [data source +class](#subsection5) and the objects it generates will have to follow to be +compatible with the tie framework. + +Data source objects are normally automatically created and destroyed by the +framework when a tie is created, or removed. This management can be explicitly +bypassed through the usage of the "dsource" type. The *[data +source](../../../../index.md#data_source)* for this type is a *data source +object* itself, and this object is outside of the scope of the tie framework and +not managed by it. In other words, this type allows the creation of ties which +talk to pre-existing *data source object*s, and these objects will survive the +removal of the ties using them as well. + +## REGISTERING A NEW DATA SOURCE CLASS + +After a [data source class](#subsection5) has been written it is necessary to +register it as a new type with the framework. + + - __::tie::register__ *dsclasscmd* __as__ *dstype* + + Using this command causes the tie framework to remember the class command + *dsclasscmd* of a [data source class](#subsection5) under the type name + *dstype*. + + After the call the argument *dstype* of the basic user command + __::tie::tie__ will accept *dstype* as a type name and translate it + internally to the appropriate class command for the creation of [data source + objects](#subsection3) for the new *[data + source](../../../../index.md#data_source)*. + +## DATA SOURCE CLASS + +Each data source class is represented by a single command, also called the +*class command*, or *object creation command*. Its syntax is + + - __dsclasscmd__ *objname* ?*dsname*...? + + The first argument of the class command is the name of the *data source + object* to create. The framework itself will always supply the string + __%AUTO%__, to signal that the class command has to generate not only the + object, but the object name as well. + + This is followed by a series of arguments identifying the data source the + new object is for. These are the same *dsname* arguments which are given to + the basic user command __::tie::tie__. Their actual meaning is dependent on + the *data source class*. + + The result of the class command has to be the fully-qualified name of the + new *data source object*, i.e. the name of the *object command*. The + interface this command has to follow is described in the section [DATA + SOURCE OBJECT API](#subsection6) + +## DATA SOURCE OBJECT API + +Please read the section [DATA SOURCE CLASS](#subsection5) first, to know how to +generate new *object commands*. + +Each *object command* for a *[data source](../../../../index.md#data_source)* +object has to provide at least the methods listed below for proper +inter-operation with the tie framework. Note that the names of most of the +methods match the subcommands of the builtin +__[array](../../../../index.md#array)__ command. + + - __ds__ __destroy__ + + This method is called when the object __ds__ is destroyed. It now has to + release all its internal resources associated with the external data source. + + - __ds__ __names__ + + This command has to return a list containing the names of all keys found in + the *[data source](../../../../index.md#data_source)* the object talks to. + This is equivalent to __array names__. + + - __ds__ __size__ + + This command has to return an integer number specifying the number of keys + found in the *[data source](../../../../index.md#data_source)* the object + talks to. This is equivalent to __array size__. + + - __ds__ __get__ + + This command has to return a dictionary containing the data found in the + *[data source](../../../../index.md#data_source)* the object talks to. This + is equivalent to __array get__. + + - __ds__ __set__ *dict* + + This command takes a dictionary and adds its contents to the data source the + object talks to. This is equivalent to __array set__. + + - __ds__ __unset__ ?*pattern*? + + This command takes a pattern and removes all elements whose keys matching it + from the *[data source](../../../../index.md#data_source)*. If no pattern is + specified it defaults to __*__, causing the removal of all elements. This is + nearly equivalent to __array unset__. + + - __ds__ __setv__ *index* *value* + + This command has to save the *value* in the *[data + source](../../../../index.md#data_source)* the object talks to, under the + key *index*. + + The result of the command is ignored. If an error is thrown then this error + will show up as error of the set operation which caused the method call. + + - __ds__ __unsetv__ *index* + + This command has to remove the value under the key *index* from the *[data + source](../../../../index.md#data_source)* the object talks to. + + The result of the command is ignored. If an error is thrown then this error + will show up as error of the unset operation which caused the method call. + + - __ds__ __getv__ *index* + + This command has to return the value for the key *index* in the *[data + source](../../../../index.md#data_source)* the object talks to. + +And here a small table comparing the *[data +source](../../../../index.md#data_source)* methods to the regular Tcl commands +for accessing an array. + + Regular Tcl Data source + ----------- ----------- + array names a ds names + array size a ds size + array get a ds get + array set a dict ds set dict + array unset a pattern ds unset ?pattern? + ----------- ----------- + set a($idx) $val ds setv idx val + unset a($idx) ds unsetv idx + $a($idx) ds getv idx + ----------- ----------- + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *tie* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[array](../../../../index.md#array), [database](../../../../index.md#database), +[file](../../../../index.md#file), [metakit](../../../../index.md#metakit), +[persistence](../../../../index.md#persistence), +[tie](../../../../index.md#tie), [untie](../../../../index.md#untie) + +# CATEGORY + +Programming tools + +# COPYRIGHT + +Copyright © 2004-2008 Andreas Kupries ADDED embedded/md/tcllib/files/modules/tie/tie_std.md Index: embedded/md/tcllib/files/modules/tie/tie_std.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/tie/tie_std.md @@ -0,0 +1,74 @@ + +[//000000001]: # (tie - Tcl Data Structures) +[//000000002]: # (Generated from file 'tie_std.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tie(n) 1.1 tcllib "Tcl Data Structures") + +# NAME + +tie - Array persistence, standard data sources + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require tie::std::log ?1.0? +package require tie::std::array ?1.0? +package require tie::std::rarray ?1.0.1? +package require tie::std::file ?1.0.4? +package require tie::std::growfile ?1.0? +package require tie::std::dsource ?1.0? + +# DESCRIPTION + +The packages listed as requirements for this document are internal packages +providing the standard data sources of package __[tie](tie.md)__, as described +in section *STANDARD DATA SOURCE TYPES* of __[tie](tie.md)__'s documentation. + +They are automatically loaded and registered by __[tie](tie.md)__ when it itself +is requested, and as such there is no need to request them on their own, +although it is possible to do so. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *tie* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[array](../../../../index.md#array), [database](../../../../index.md#database), +[file](../../../../index.md#file), [metakit](../../../../index.md#metakit), +[persistence](../../../../index.md#persistence), +[tie](../../../../index.md#tie), [untie](../../../../index.md#untie) + +# CATEGORY + +Programming tools + +# COPYRIGHT + +Copyright © 2008-2015 Andreas Kupries ADDED embedded/md/tcllib/files/modules/tiff/tiff.md Index: embedded/md/tcllib/files/modules/tiff/tiff.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/tiff/tiff.md @@ -0,0 +1,257 @@ + +[//000000001]: # (tiff - TIFF image manipulation) +[//000000002]: # (Generated from file 'tiff.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tiff(n) 0.2.1 tcllib "TIFF image manipulation") + +# NAME + +tiff - TIFF reading, writing, and querying and manipulation of meta data + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [VARIABLES](#section3) + + - [LIMITATIONS](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require tiff ?0.2.1? + +[__::tiff::isTIFF__ *file*](#1) +[__::tiff::byteOrder__ *file*](#2) +[__::tiff::numImages__ *file*](#3) +[__::tiff::dimensions__ *file* ?image?](#4) +[__::tiff::imageInfo__ *file* ?image?](#5) +[__::tiff::entries__ *file* ?image?](#6) +[__::tiff::getEntry__ *file* *entry* ?image?](#7) +[__::tiff::addEntry__ *file* *entry* ?image?](#8) +[__::tiff::deleteEntry__ *file* *entry* ?image?](#9) +[__::tiff::getImage__ *file* ?image?](#10) +[__::tiff::writeImage__ *image* *file* ?entry?](#11) +[__::tiff::nametotag__ *names*](#12) +[__::tiff::tagtoname__ *tags*](#13) +[__::tiff::debug__ *file*](#14) + +# DESCRIPTION + +This package provides commands to query, modify, read, and write TIFF images. +TIFF stands for *Tagged Image File Format* and is a standard for lossless +storage of photographical images and associated metadata. It is specified at +[http://partners.adobe.com/public/developer/tiff/index.html](http://partners.adobe.com/public/developer/tiff/index.html). + +Multiple images may be stored in a single TIFF file. The ?image? options to the +functions in this package are for accessing images other than the first. Data in +a TIFF image is stored as a series of tags having a numerical value, which are +represented in either a 4 digit hexadecimal format or a string name. For a +reference on defined tags and their meanings see +[http://www.awaresystems.be/imaging/tiff/tifftags.html](http://www.awaresystems.be/imaging/tiff/tifftags.html) + +# COMMANDS + + - __::tiff::isTIFF__ *file* + + Returns a boolean value indicating if *file* is a TIFF image. + + - __::tiff::byteOrder__ *file* + + Returns either __big__ or __little__. Throws an error if *file* is not a + TIFF image. + + - __::tiff::numImages__ *file* + + Returns the number of images in *file*. Throws an error if *file* is not a + TIFF image. + + - __::tiff::dimensions__ *file* ?image? + + Returns the dimensions of image number ?image? in *file* as a list of the + horizontal and vertical pixel count. Throws an error if *file* is not a TIFF + image. + + - __::tiff::imageInfo__ *file* ?image? + + Returns a dictionary with keys __ImageWidth__, __ImageLength__, + __BitsPerSample__, __Compression__, __PhotometricInterpretation__, + __ImageDescription__, __Orientation__, __XResolution__, __YResolution__, + __ResolutionUnit__, __DateTime__, __Artist__, and __HostComputer__. The + values are the associated properties of the TIFF ?image? in *file*. Values + may be empty if the associated tag is not present in the file. + + puts [::tiff::imageInfo photo.tif] + + ImageWidth 686 ImageLength 1024 BitsPerSample {8 8 8} Compression 1 + PhotometricInterpretation 2 ImageDescription {} Orientation 1 + XResolution 170.667 YResolution 170.667 ResolutionUnit 2 DateTime {2005:12:28 19:44:45} + Artist {} HostComputer {} + + There is nothing special about these tags, this is simply a convience + procedure which calls __getEntry__ with common entries. Throws an error if + *file* is not a TIFF image. + + - __::tiff::entries__ *file* ?image? + + Returns a list of all entries in the given *file* and ?image? in hexadecimal + format. Throws an error if *file* is not a TIFF image. + + - __::tiff::getEntry__ *file* *entry* ?image? + + Returns the value of *entry* from image ?image? in the TIFF *file*. *entry* + may be a list of multiple entries. If an entry does not exist, an empty + string is returned + + set data [::tiff::getEntry photo.tif {0131 0132}] + puts "file was written at [lindex $data 0] with software [lindex $data 1]" + + Throws an error if *file* is not a TIFF image. + + - __::tiff::addEntry__ *file* *entry* ?image? + + Adds the specified entries to the image named by ?image? (default 0), or + optionally __all__. *entry* must be a list where each element is a list of + tag, type, and value. If a tag already exists, it is overwritten. + + ::tiff::addEntry photo.tif {{010e 2 "an example photo"} {013b 2 "Aaron F"}} + + The data types are defined as follows + + * __1__ + + BYTE (8 bit unsigned integer) + + * __2__ + + ASCII + + * __3__ + + SHORT (16 bit unsigned integer) + + * __4__ + + LONG (32 bit unsigned integer) + + * __5__ + + RATIONAL + + * __6__ + + SBYTE (8 bit signed byte) + + * __7__ + + UNDEFINED (uninterpreted binary data) + + * __8__ + + SSHORT (signed 16 bit integer) + + * __9__ + + SLONG (signed 32 bit integer) + + * __10__ + + SRATIONAL + + * __11__ + + FLOAT (32 bit floating point number) + + * __12__ + + DOUBLE (64 bit floating point number) + + Throws an error if *file* is not a TIFF image. + + - __::tiff::deleteEntry__ *file* *entry* ?image? + + Deletes the specified entries from the image named by ?image? (default 0), + or optionally __all__. Throws an error if *file* is not a TIFF image. + + - __::tiff::getImage__ *file* ?image? + + Returns the name of a Tk image containing the image at index ?image? from + *file* Throws an error if *file* is not a TIFF image, or if image is an + unsupported format. Supported formats are uncompressed 24 bit RGB and + uncompressed 8 bit palette. + + - __::tiff::writeImage__ *image* *file* ?entry? + + Writes the contents of the Tk image *image* to a tiff file *file*. Files are + written in the 24 bit uncompressed format, with big endian byte order. + Additional entries to be added to the image may be specified, in the same + format as __tiff::addEntry__ + + - __::tiff::nametotag__ *names* + + Returns a list with *names* translated from string to 4 digit format. 4 + digit names in the input are passed through unchanged. Strings without a + defined tag name will throw an error. + + - __::tiff::tagtoname__ *tags* + + Returns a list with *tags* translated from 4 digit to string format. If a + tag does not have a defined name it is passed through unchanged. + + - __::tiff::debug__ *file* + + Prints everything we know about the given file in a nice format. + +# VARIABLES + +The mapping of 4 digit tag names to string names uses the array +::tiff::tiff_tags. The reverse mapping uses the array ::tiff::tiff_sgat. + +# LIMITATIONS + + 1. Cannot write exif ifd + + 1. Reading limited to uncompressed 8 bit rgb and 8 bit palletized images + + 1. Writing limited to uncompressed 8 bit rgb + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *tiff* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[image](../../../../index.md#image), [tif](../../../../index.md#tif), +[tiff](../../../../index.md#tiff) + +# CATEGORY + +File formats + +# COPYRIGHT + +Copyright © 2005-2006, Aaron Faupell ADDED embedded/md/tcllib/files/modules/tool/meta.md Index: embedded/md/tcllib/files/modules/tool/meta.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/tool/meta.md @@ -0,0 +1,209 @@ + +[//000000001]: # (oo::util - Utility commands for TclOO) +[//000000002]: # (Generated from file 'meta.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (oo::util(n) 1.2.2 tcllib "Utility commands for TclOO") + +# NAME + +oo::util - Utility commands for TclOO + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [AUTHORS](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require oo::util ?1.2.2? + +[__mymethod__ *method* ?*arg*...?](#1) +[__classmethod__ *name* *arguments* *body*](#2) +[__classvariable__ ?*arg*...?](#3) +[__link__ *method*...](#4) +[__link__ {*alias* *method*}...](#5) +[__ooutil::singleton__ ?*arg*...?](#6) + +# DESCRIPTION + +This package provides a convenience command for the easy specification of +instance methods as callback commands, like timers, file events, Tk bindings, +etc. + +# COMMANDS + + - __mymethod__ *method* ?*arg*...? + + This command is available within instance methods. It takes a method name + and, possibly, arguments for the method and returns a command prefix which, + when executed, will invoke the named method of the object we are in, with + the provided arguments, and any others supplied at the time of actual + invokation. + + Note: The command is equivalent to and named after the command provided by + the OO package __[snit](../snit/snit.md)__ for the same purpose. + + - __classmethod__ *name* *arguments* *body* + + This command is available within class definitions. It takes a method name + and, possibly, arguments for the method and creates a method on the class, + available to a user of the class and of derived classes. + + Note: The command is equivalent to the command __typemethod__ provided by + the OO package __[snit](../snit/snit.md)__ for the same purpose. + + Example + + oo::class create ActiveRecord { + classmethod find args { puts "[self] called with arguments: $args" } + } + oo::class create Table { + superclass ActiveRecord + } + puts [Table find foo bar] + # ====== + # which will write + # ====== + # ::Table called with arguments: foo bar + + - __classvariable__ ?*arg*...? + + This command is available within instance methods. It takes a series of + variable names and makes them available in the method's scope. The + originating scope for the variables is the class (instance) the object + instance belongs to. In other words, the referenced variables are shared + between all instances of their class. + + Note: The command is roughly equivalent to the command __typevariable__ + provided by the OO package __[snit](../snit/snit.md)__ for the same purpose. + The difference is that it cannot be used in the class definition itself. + + Example: + + % oo::class create Foo { + method bar {z} { + classvariable x y + return [incr x $z],[incr y] + } + } + ::Foo + % Foo create a + ::a + % Foo create b + ::b + % a bar 2 + 2,1 + % a bar 3 + 5,2 + % b bar 7 + 12,3 + % b bar -1 + 11,4 + % a bar 0 + 11,5 + + - __link__ *method*... + + - __link__ {*alias* *method*}... + + This command is available within instance methods. It takes a list of method + names and/or pairs of alias- and method-name and makes the named methods + available to all instance methods without requiring the __my__ command. + + The alias name under which the method becomes available defaults to the + method name, except where explicitly specified through an alias/method pair. + + Examples: + + link foo + # The method foo is now directly accessible as foo instead of my foo. + + link {bar foo} + # The method foo is now directly accessible as bar. + + link a b c + # The methods a, b, and c all become directly acessible under their + # own names. + + The main use of this command is expected to be in instance constructors, for + convenience, or to set up some methods for use in a mini DSL. + + - __ooutil::singleton__ ?*arg*...? + + This command is a meta-class, i.e. a variant of the builtin __oo::class__ + which ensures that it creates only a single instance of the classes defined + with it. + + Syntax and results are like for __oo::class__. + + Example: + + % oo::class create example { + self mixin singleton + method foo {} {self} + } + ::example + % [example new] foo + ::oo::Obj22 + % [example new] foo + ::oo::Obj22 + +# AUTHORS + +Donal Fellows, Andreas Kupries + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *oo::util* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[snit(n)](../snit/snit.md) + +# KEYWORDS + +[TclOO](../../../../index.md#tcloo), [callback](../../../../index.md#callback), +[class methods](../../../../index.md#class_methods), [class +variables](../../../../index.md#class_variables), [command +prefix](../../../../index.md#command_prefix), +[currying](../../../../index.md#currying), [method +reference](../../../../index.md#method_reference), [my +method](../../../../index.md#my_method), +[singleton](../../../../index.md#singleton) + +# CATEGORY + +Utility + +# COPYRIGHT + +Copyright © 2011-2015 Andreas Kupries, BSD licensed ADDED embedded/md/tcllib/files/modules/tool/tool.md Index: embedded/md/tcllib/files/modules/tool/tool.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/tool/tool.md @@ -0,0 +1,305 @@ + +[//000000001]: # (tool - Standardized OO Framework for development) +[//000000002]: # (Generated from file 'tool.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tool(n) 0.4.2 tcllib "Standardized OO Framework for development") + +# NAME + +tool - TclOO Library (TOOL) Framework + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Keywords](#section2) + + - [Public Object Methods](#section3) + + - [Private Object Methods](#section4) + + - [AUTHORS](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require sha1 +package require dicttool +package require oo::meta +package require oo::dialect + +[tool::define __class_method__ *arglist* *body*](#1) +[tool::define __[array](../../../../index.md#array)__ *name* *contents*](#2) +[tool::define __array_ensemble__ *methodname* *varname* ?cases?](#3) +[tool::define __dict_ensemble__ *methodname* *varname* ?cases?](#4) +[tool::define __[method](../../../../index.md#method)__ *methodname* *arglist* *body*](#5) +[tool::define __option__ *name* *dictopts*](#6) +[tool::define __property__ ?branch? *field* *value*](#7) +[tool::define __variable__ *name* *value*](#8) +[*object* __cget__ *option*](#9) +[*object* __configure__ ?keyvaluelist?](#10) +[*object* __configure__ *field* *value* ?field? ?value? ?...?](#11) +[*object* __configurelist__ ?keyvaluelist?](#12) +[*object* __forward__ *stub* *forward*](#13) +[*object* __graft__ *stub* *forward*](#14) +[*object* __InitializePublic__](#15) +[*object* __Eval_Script__ ?script?](#16) +[*object* __Option_Default__ *field*](#17) + +# DESCRIPTION + +This module implements the Tcl Object Oriented Library framework, or *TOOL*. It +is intended to be a general purpose framework that is useable in its own right, +and easily extensible. + +TOOL defines a metaclass with provides several additional keywords to the TclOO +description langauge, default behaviors for its consituent objects, and top-down +integration with the capabilities provided by the __oo::meta__ package. + +The TOOL metaclass was build with the __oo::dialect__ package, and thus can be +used as the basis for additional metaclasses. As a metaclass, TOOL has it's own +"class" class, "object" class, and define namespace. + + package require tool + + # tool::class workds just like oo::class + tool::class create myclass { + } + + # tool::define works just like oo::define + tool::define myclass method noop {} {} + + # tool::define and tool::class understand additional keywords + tool::define myclass array_ensemble mysettings mysettings {} + + # And tool interoperates with oo::define + oo::define myclass method do_something {} { return something } + + # TOOL and TclOO objects are interchangeable + oo::class create myooclass { + superclass myclass + } + +Several manual pages go into more detail about specific keywords and methods. + + - __tool::array_ensemble__ + + - __[tool::dict_ensemble](tool_dict_ensemble.md)__ + + - __tool::method_ensemble__ + + - __tool::object__ + + - __tool::option_handling__ + +# Keywords + +TOOL adds new (or modifies) keywords used in the definitions of classes. +However, the new keywords are only available via calls to *tool::class create* +or *tool::define* + + - tool::define __class_method__ *arglist* *body* + + Defines a method for the class object itself. This method will be passed on + to descendents of the class, unlike __self method__. + + - tool::define __[array](../../../../index.md#array)__ *name* *contents* + + Declares a variable *name* which will be initialized as an array, populated + with *contents* for objects of this class, as well as any objects for + classes which are descendents of this class. + + - tool::define __array_ensemble__ *methodname* *varname* ?cases? + + Declares a method ensemble *methodname* which will control access to + variable *varname*. Cases are a key/value list of method names and bodies + which will be overlaid on top of the standard template. See + __tool::array_ensemble__. + + One method name is reserved: __initialize__. __initialize__ Declares the + initial values to be populated in the array, as a key/value list, and will + not be expressed as a method for the ensemble. + + - tool::define __dict_ensemble__ *methodname* *varname* ?cases? + + Declares a method ensemble *methodname* which will control access to + variable *varname*. Cases are a key/value list of method names and bodies + which will be overlaid on top of the standard template. See + __[tool::dict_ensemble](tool_dict_ensemble.md)__. + + One method name is reserved: __initialize__. __initialize__ Declares the + initial values to be populated in the array, as a key/value list, and will + not be expressed as a method for the ensemble. + + - tool::define __[method](../../../../index.md#method)__ *methodname* *arglist* *body* + + If *methodname* contains ::, the method is considered to be part of a method + ensemble. See __tool::method_ensembles__. Otherwise this command behaves + exactly like the standard __oo::define__ + __[method](../../../../index.md#method)__ command. + + - tool::define __option__ *name* *dictopts* + + Declares an option. *dictopts* is a key/value list defining parameters for + the option. See __tool::option_handling__. + + tool::class create myclass { + option color { + post-command: {puts [list %self%'s %field% is now %value%]} + default: green + } + } + myclass create foo + foo configure color purple + > foo's color is now purple + + - tool::define __property__ ?branch? *field* *value* + + Defines a new leaf in the class metadata tree. With no branch, the leaf will + appear in the *const* section, accessible by either the object's + __property__ method, or via __oo::meta::info__ *class* __get const__ + *field*: + + - tool::define __variable__ *name* *value* + + Declares a variable *name* which will be initialized with the value *value* + for objects of this class, as well as any objects for classes which are + descendents of this class. + +# Public Object Methods + +The TOOL object mother of all classes defines several methods to enforces +consistent behavior throughout the framework. + + - *object* __cget__ *option* + + Return the value of this object's option *option*. If the __property + options_strict__ is true for this class, calling an option which was not + declared by the __option__ keyword will throw an error. In all other cases + if the value is present in the object's *options* array that value is + returned. If it does not exist, the object will attempt to retrieve a + property of the same name. + + - *object* __configure__ ?keyvaluelist? + + - *object* __configure__ *field* *value* ?field? ?value? ?...? + + This command will inject new values into the objects *options* array, + according to the rules as set forth by the option descriptions. See + __tool::option_handling__ for details. __configure__ will strip leading -'s + off of field names, allowing it to behave in a quasi-backward compatible + manner to tk options. + + - *object* __configurelist__ ?keyvaluelist? + + This command will inject new values into the objects *options* array, + according to the rules as set forth by the option descriptions. This command + will perform validation and alternate storage rules. It will not invoke + trigger rules. See __tool::option_handling__ for details. + + - *object* __forward__ *stub* *forward* + + A passthrough to __oo:objdefine [self] forward__ + + - *object* __graft__ *stub* *forward* + + Delegates the ** method to the object or command designated by + *forward* + + tool::object create A + tool::object create B + A graft buddy B + A configure color red + B configure color blue + A cget color + > red + A cget color + > blue + +# Private Object Methods + + - *object* __InitializePublic__ + + Consults the metadata for the class to ensure every array, option, and + variable which has been declared but not initialized is initialized with the + default value. This method is called by the constructor and the morph + method. It is safe to invoke multiple times. + + - *object* __Eval_Script__ ?script? + + Executes a block of text within the namespace of the object. Lines that + begin with a # are ignored as comments. Commands that begin with :: are + interpreted as calling a global command. All other Tcl commands that lack a + "my" prefix are given one, to allow the script to exercise internal methods. + This method is intended for configuration scripts, where the object's + methods are intepreting a domain specific language. + + tool::class myclass { + constructor script { + my Eval_Script $script + } + method node {nodename info} { + my variable node + dict set node $nodename $info + } + method get {args} { + my variable node + return [dict get $node $args] + } + } + myclass create movies { + # This block of code is executed by the object + node {The Day the Earth Stood Still} { + date: 1952 + characters: {GORT Klatoo} + } + } + movies get {The Day the Earth Stood Still} date: + > 1952 + + - *object* __Option_Default__ *field* + + Computes the default value for an option. See __tool::option_handling__. + +# AUTHORS + +Sean Woods + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *tcloo* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[TOOL](../../../../index.md#tool), [TclOO](../../../../index.md#tcloo), +[framework](../../../../index.md#framework) + +# CATEGORY + +TclOO + +# COPYRIGHT + +Copyright © 2015 Sean Woods ADDED embedded/md/tcllib/files/modules/tool/tool_dict_ensemble.md Index: embedded/md/tcllib/files/modules/tool/tool_dict_ensemble.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/tool/tool_dict_ensemble.md @@ -0,0 +1,77 @@ + +[//000000001]: # (tool::dict_ensemble - Standardized OO Framework for development) +[//000000002]: # (Generated from file 'tool_dict_ensemble.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tool::dict_ensemble(n) 0.4.2 tcllib "Standardized OO Framework for development") + +# NAME + +tool::dict_ensemble - Dictionary Tools + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [AUTHORS](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require tool ?0.4.2? + +[*object* *ensemble* __add__ *field*](#1) + +# DESCRIPTION + +The __dict_ensemble__ command is a keyword added by __[tool](tool.md)__. It +defines a public variable (stored as a dict), and an access function to +manipulated and access the values stored in that dict. + + - *object* *ensemble* __add__ *field* + + ] *value* *value ...*] Adds elements to a list maintained with the *field* + leaf of the dict maintained my this ensemble. Declares a variable *name* + which will be initialized as an array, populated with *contents* for objects + of this class, as well as any objects for classes which are descendents of + this class. + +# AUTHORS + +Sean Woods + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *tool* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[TOOL](../../../../index.md#tool), [TclOO](../../../../index.md#tcloo) + +# CATEGORY + +Utility + +# COPYRIGHT + +Copyright © 2015 Sean Woods ADDED embedded/md/tcllib/files/modules/transfer/connect.md Index: embedded/md/tcllib/files/modules/transfer/connect.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/transfer/connect.md @@ -0,0 +1,277 @@ + +[//000000001]: # (transfer::connect - Data transfer facilities) +[//000000002]: # (Generated from file 'connect.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (transfer::connect(n) 0.2 tcllib "Data transfer facilities") + +# NAME + +transfer::connect - Connection setup + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Package commands](#subsection1) + + - [Object command](#subsection2) + + - [Object methods](#subsection3) + + - [Options](#subsection4) + + - [Secure connections](#section3) + + - [TLS Security Considerations](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require snit ?1.0? +package require transfer::connect ?0.2? + +[__transfer::connect__ *objectName* ?*options*...?](#1) +[*objectName* __method__ ?*arg arg ...*?](#2) +[*objectName* __destroy__](#3) +[*objectName* __connect__ *command*](#4) + +# DESCRIPTION + +This package provides objects holding enough information to enable them to +either actively connect to a counterpart, or to passively wait for a connection +from said counterpart. I.e. any object created by this packages is always in one +of two complementary modes, called *[active](../../../../index.md#active)* (the +object initiates the connection) and *[passive](../../../../index.md#passive)* +(the object receives the connection). + +Of the two objects in a connecting pair one has to be configured for +*[active](../../../../index.md#active)* mode, and the other then has to be +configured for *[passive](../../../../index.md#passive)* mode. This establishes +which of the two partners connects to whom (the +*[active](../../../../index.md#active)* to the other), or, who is waiting on +whom (the *[passive](../../../../index.md#passive)* on the other). Note that +this is completely independent of the direction of any data transmission using +the connection after it has been established. An active object can, after +establishing the connection, either transmit or receive data. Equivalently the +passive object can do the same after the waiting for its partner has ended. + +# API + +## Package commands + + - __transfer::connect__ *objectName* ?*options*...? + + This command creates a new connection object with an associated Tcl command + whose name is *objectName*. This *[object](../../../../index.md#object)* + command is explained in full detail in the sections [Object + command](#subsection2) and [Object methods](#subsection3). The set of + supported *options* is explained in section [Options](#subsection4). + + The object command will be created under the current namespace if the + *objectName* is not fully qualified, and in the specified namespace + otherwise. The fully qualified name of the object command is returned as the + result of the command. + +## Object command + +All objects created by the __::transfer::connect__ command have the following +general form: + + - *objectName* __method__ ?*arg arg ...*? + + The method __method__ and its *arg*'uments determine the exact behavior of + the command. See section [Object methods](#subsection3) for the detailed + specifications. + +## Object methods + + - *objectName* __destroy__ + + This method destroys the object. This is safe to do for an + *[active](../../../../index.md#active)* object when a connection has been + started, as the completion callback is synchronous. For a + *[passive](../../../../index.md#passive)* object currently waiting for its + partner to establish the connection however this is not safe and will cause + errors later on, when the connection setup completes and tries to access the + now missing data structures of the destroyed object. + + - *objectName* __connect__ *command* + + This method starts the connection setup per the configuration of the object. + When the connection is established the callback *command* will be invoked + with one additional argument, the channel handle of the socket over which + data can be transfered. + + The detailed behaviour of the method depends on the configured mode. + + * *[active](../../../../index.md#active)* + + The connection setup is done synchronously. The object waits until the + connection is established. The method returns the empty string as its + result. + + * *[passive](../../../../index.md#passive)* + + The connection setup is done asynchronously. The method returns + immediately after a listening socket has been set up. The connection + will be established in the background. The method returns the port + number of the listening socket, for use by the caller. One important use + is the transfer of this information to the counterpart so that it knows + where it has to connect to. + + This is necessary as the object might have been configured for port + __0__, allowing the operating system to choose the actual port it will + listen on. + + The listening port is closed immediately when the connection was + established by the partner, to keep the time interval small within which + a third party can connect to the port too. Even so it is recommended to + use additional measures in the protocol outside of the connect and + transfer object to ensure that a connection is not used with an + unidentified/unauthorized partner One possibility for this is the use of + SSL/TLS. See the option __-socketcmd__ and section [Secure + connections](#section3) for information on how to do this. + +## Options + +Connection objects support the set of options listed below. + + - __-mode__ *mode* + + This option specifies the mode the object is in. It is optional and defaults + to __active__ mode. The two possible modes are: + + * __active__ + + In this mode the two options __-host__ and __-port__ are relevant and + specify the host and TCP port the object has to connect to. The host is + given by either name or IP address. + + * __passive__ + + In this mode the option __-host__ has no relevance and is ignored should + it be configured. The only option the object needs is __-port__, and it + specifies the TCP port on which the listening socket is opened to await + the connection from the partner. + + - __-host__ *hostname-or-ipaddr* + + This option specifies the host to connect to in + *[active](../../../../index.md#active)* mode, either by name or ip-address. + An object configured for *[passive](../../../../index.md#passive)* mode + ignores this option. + + - __-port__ *int* + + For *[active](../../../../index.md#active)* mode this option specifies the + port the object is expected to connect to. For + *[passive](../../../../index.md#passive)* mode however it is the port where + the object creates the listening socket waiting for a connection. It + defaults to __0__, which allows the OS to choose the actual port to listen + on. + + - __-socketcmd__ *command* + + This option allows the user to specify which command to use to open a + socket. The default is to use the builtin __::socket__. Any compatible with + that command is allowed. + + The envisioned main use is the specfication of __tls::socket__. I.e. this + option allows the creation of secure transfer channels, without making this + package explicitly dependent on the __[tls](../../../../index.md#tls)__ + package. + + See also section [Secure connections](#section3). + + - __-encoding__ encodingname + + - __-eofchar__ eofspec + + - __-translation__ transspec + + These options are the same as are recognized by the builtin command + __fconfigure__. They provide the configuration to be set for the channel + between the two partners after it has been established, but before the + callback is invoked (See method __connect__). + +# Secure connections + +One way to secure connections made by objects of this package is to require the +package __[tls](../../../../index.md#tls)__ and then configure the option +__-socketcmd__ to force the use of command __tls::socket__ to open the socket. + + # Load and initialize tls + package require tls + tls::init -cafile /path/to/ca/cert -keyfile ... + + # Create a connector with secure socket setup, + transfer::connect C -socketcmd tls::socket ... + ... + +# TLS Security Considerations + +This package uses the __[TLS](../../../../index.md#tls)__ package to handle the +security for __https__ urls and other socket connections. + +Policy decisions like the set of protocols to support and what ciphers to use +are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this +package itself however. Such decisions are the responsibility of whichever +application is using the package, and are likely influenced by the set of +servers the application will talk to as well. + +For example, in light of the recent [POODLE +attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html) +discovered by Google many servers will disable support for the SSLv3 protocol. +To handle this change the applications using __[TLS](../../../../index.md#tls)__ +must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__ +itself. Such a patch may be as simple as generally activating __tls1__ support, +as shown in the example below. + + package require tls + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol + + ... your own application code ... + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *transfer* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[active](../../../../index.md#active), [channel](../../../../index.md#channel), +[connection](../../../../index.md#connection), +[passive](../../../../index.md#passive), [secure](../../../../index.md#secure), +[ssl](../../../../index.md#ssl), [tls](../../../../index.md#tls), +[transfer](../../../../index.md#transfer) + +# CATEGORY + +Transfer module + +# COPYRIGHT + +Copyright © 2006-2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/transfer/copyops.md Index: embedded/md/tcllib/files/modules/transfer/copyops.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/transfer/copyops.md @@ -0,0 +1,188 @@ + +[//000000001]: # (transfer::copy - Data transfer facilities) +[//000000002]: # (Generated from file 'copyops.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (transfer::copy(n) 0.2 tcllib "Data transfer facilities") + +# NAME + +transfer::copy - Data transfer foundation + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require transfer::copy ?0.2? + +[__transfer::copy::do__ __chan__|__string__ *data* *outchannel* ?*options*...?](#1) +[__transfer::copy::chan__ *channel* *outchannel* ?*options*...?](#2) +[__transfer::copy::string__ *string* *outchannel* ?*options*...?](#3) +[__transfer::copy::doChan__ *channel* *outchannel* *optvar*](#4) +[__transfer::copy::doString__ *string* *outchannel* *optvar*](#5) +[__transfer::copy::options__ *outchannel* *optionlist* *optvar*](#6) + +# DESCRIPTION + +This package provides a number of commands for the asynchronous of information +contained in either a string or channel. The main point of this package is that +the commands here provide a nicer callback API than the builtin command +__fcopy__, making the use of these facilities simpler than the builtin. + +# API + + - __transfer::copy::do__ __chan__|__string__ *data* *outchannel* ?*options*...? + + This command transfers the information in *data* to the *outchannel*, + according to the *options*. The type of the information in *data* is + determined by the first argument. + + The options available to this command are the same as are available to the + command __transfer::copy::options__, and explained there. + + * __chan__ + + The argument *data* contains the handle of a channel and the actual + infomration to transfer is read from that channel. + + * __string__ + + The argument *data* contains a string and this is the information to be + transfered. + + - __transfer::copy::chan__ *channel* *outchannel* ?*options*...? + + This command is a shorter and more direct form for the command + __transfer::copy::do chan__. + + - __transfer::copy::string__ *string* *outchannel* ?*options*...? + + This command is a shorter and more direct form for the command + __transfer::copy::do string__. + + - __transfer::copy::doChan__ *channel* *outchannel* *optvar* + + This command is an alternate form of __transfer::copy::chan__ which reads + its options out of the array variable named by *optvar* instead of from a + variable length argument list. + + - __transfer::copy::doString__ *string* *outchannel* *optvar* + + This command is an alternate form of __transfer::copy::string__ which reads + its options out of the array variable named by *optvar* instead of from a + variable length argument list. + + - __transfer::copy::options__ *outchannel* *optionlist* *optvar* + + This command is the option processor used by all the commands above which + read their options from a variable length argument list. It first reads + default settings from the channel handle *outchannel*, then processes the + list of options in *optionlist*, at last stores the results in the array + variable named by *optvar*. The contents of that variable are in a format + which is directly understood by all the commands above which read their + options out of an array variable. + + The recognized options are: + + * __-blocksize__ *int* + + This option specifies the size of the chunks to transfer in one + operation. It is optional and defaults to the value of __-buffersize__ + as configured for the output channel. + + If specified its value has to be an integer number greater than zero. + + * __-command__ *commandprefix* + + This option specifies the completion callback of the operation. This + option has to be specified. An error will be thrown if it is not, or if + the empty list was specified as argument to it. + + Its value has to be a command prefix, i.e. a list whose first word is + the command to execute, followed by words containing fixed arguments. + When the callback is invoked one or two additional arguments are + appended to the prefix. The first argument is the number of bytes which + were transfered. The optional second argument is an error message and + added if and only if an error occured during the the transfer. + + * __-progress__ *commandprefix* + + This option specifies the progress callback of the operation. It is + optional and defaults to the empty list. This last possibility signals + that no feedback was asked for and disabled it. + + Its value has to be a command prefix, see above, __-command__ for a more + detailed explanation. When the callback is invoked a single additional + arguments is appended to the prefix. This argument is the number of + bytes which were transfered so far. + + * __-size__ *int* + + This option specifies the number of bytes to read from the input data + and transfer. It is optional and defaults to "Transfer everything". Its + value has to be an integer number and any value less than zero has the + same meaning, i.e. to transfer all available data. Any other value is + the amount of bytes to transfer. + + All transfer commands will throw error an when their user tries to + transfer more data than is available in the input. This happens + immediately, before the transfer is actually started, should the input + be a string. Otherwise the, i.e. for a channel as input, the error is + thrown the moment the underflow condition is actually detected. + + * __-encoding__ *encodingname* + + * __-eofchar__ *eofspec* + + * __-translation__ *transspec* + + These options are the same as are recognized by the builtin command + __fconfigure__ and provide the settings for the output channel which are + to be active during the transfer, and only then. I.e. the settings of + the output channel before the transfer are saved, and restored at the + end of a transfer, regardless of its success or failure. None of these + options are required, and they default to the settings of the output + channel if not specified. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *transfer* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel](../../../../index.md#channel), [copy](../../../../index.md#copy), +[transfer](../../../../index.md#transfer) + +# CATEGORY + +Transfer module + +# COPYRIGHT + +Copyright © 2006-2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/transfer/ddest.md Index: embedded/md/tcllib/files/modules/transfer/ddest.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/transfer/ddest.md @@ -0,0 +1,176 @@ + +[//000000001]: # (transfer::data::destination - Data transfer facilities) +[//000000002]: # (Generated from file 'ddest.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (transfer::data::destination(n) 0.2 tcllib "Data transfer facilities") + +# NAME + +transfer::data::destination - Data destination + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Object command](#subsection1) + + - [Object methods](#subsection2) + + - [Options](#subsection3) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require snit ?1.0? +package require transfer::data::destination ?0.2? + +[__transfer::data::destination__ *objectName* ?*options*...?](#1) +[*objectName* __method__ ?*arg arg ...*?](#2) +[*objectName* __destroy__](#3) +[*objectName* __put__ *chunk*](#4) +[*objectName* __done__](#5) +[*objectName* __valid__ *msgvar*](#6) +[*objectName* __receive__ *channel* *done*](#7) + +# DESCRIPTION + +This package provides objects mainly describing the destination of a data +transfer. They are also able to initiate the reception of information from a +channel into the described destination. + +# API + + - __transfer::data::destination__ *objectName* ?*options*...? + + This command creates a new data destination object with an associated Tcl + command whose name is *objectName*. This + *[object](../../../../index.md#object)* command is explained in full detail + in the sections [Object command](#subsection1) and [Object + methods](#subsection2). The set of supported *options* is explained in + section [Options](#subsection3). + + The object command will be created under the current namespace if the + *objectName* is not fully qualified, and in the specified namespace + otherwise. The fully qualified name of the object command is returned as the + result of the command. + +## Object command + +All objects created by the __::transfer::data::destination__ command have the +following general form: + + - *objectName* __method__ ?*arg arg ...*? + + The method __method__ and its *arg*'uments determine the exact behavior of + the command. See section [Object methods](#subsection2) for the detailed + specifications. + +## Object methods + + - *objectName* __destroy__ + + This method destroys the object. Doing so while the object is busy with the + reception of information from a channel will cause errors later on, when the + reception completes and tries to access the now missing data structures of + the destroyed object. + + - *objectName* __put__ *chunk* + + The main receptor method. Saves the received *chunk* of data into the + configured destination. It has to be called for each piece of data received. + + - *objectName* __done__ + + The secondary receptor method. Finalizes the receiver. It has to be called + when the receiving channel signals EOF. Afterward neither itself nor method + __put__ can be called anymore. + + - *objectName* __valid__ *msgvar* + + This method checks the configuration of the object for validity. It returns + a boolean flag as result, whose value is __True__ if the object is valid, + and __False__ otherwise. In the latter case the variable whose name is + stored in *msgvar* is set to an error message describing the problem found + with the configuration. Otherwise this variable is not touched. + + - *objectName* __receive__ *channel* *done* + + This method initiates the reception of data from the specified *channel*. + The received data will be stored into the configured destination, via calls + to the methods __put__ and __done__. When the reception completes the + command prefix *done* is invoked, with the number of received characters + appended to it as the sole additional argument. + +## Options + +All data destinations support the options listed below. It should be noted that +all are semi-exclusive, each specifying a different type of destination and +associated information. If these options are specified more than once then the +last option specified is used to actually configure the object. + + - __-channel__ *handle* + + This option specifies that the destination of the data is a channel, and its + associated argument is the handle of the channel to write the received data + to. + + - __-file__ *path* + + This option specifies that the destination of the data is a file, and its + associated argument is the path of the file to write the received data to. + + - __-variable__ *varname* + + This option specifies that the destination of the data is a variable, and + its associated argument contains the name of the variable to write the + received data to. The variable is assumed to be global or namespaced, + anchored at the global namespace. + + - __-progress__ *command* + + This option, if specified, defines a command to be invoked for each chunk of + bytes received, allowing the user to monitor the progress of the reception + of the data. The callback is always invoked with one additional argument, + the number of bytes received so far. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *transfer* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel](../../../../index.md#channel), [copy](../../../../index.md#copy), +[data destination](../../../../index.md#data_destination), +[transfer](../../../../index.md#transfer) + +# CATEGORY + +Transfer module + +# COPYRIGHT + +Copyright © 2006-2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/transfer/dsource.md Index: embedded/md/tcllib/files/modules/transfer/dsource.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/transfer/dsource.md @@ -0,0 +1,216 @@ + +[//000000001]: # (transfer::data::source - Data transfer facilities) +[//000000002]: # (Generated from file 'dsource.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (transfer::data::source(n) 0.2 tcllib "Data transfer facilities") + +# NAME + +transfer::data::source - Data source + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Package commands](#subsection1) + + - [Object command](#subsection2) + + - [Object methods](#subsection3) + + - [Options](#subsection4) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require snit ?1.0? +package require transfer::copy ?0.2? +package require transfer::data::source ?0.2? + +[__transfer::data::source__ *objectName* ?*options*...?](#1) +[*objectName* __method__ ?*arg arg ...*?](#2) +[*objectName* __destroy__](#3) +[*objectName* __type__](#4) +[*objectName* __data__](#5) +[*objectName* __size__](#6) +[*objectName* __valid__ *msgvar*](#7) +[*objectName* __transmit__ *channel* *blocksize* *done*](#8) + +# DESCRIPTION + +This package provides objects mainly describing the origin of some data to +transfer. They are also able to initiate transfers of the described information +to a channel using the foundation package __[transfer::copy](copyops.md)__. + +# API + +## Package commands + + - __transfer::data::source__ *objectName* ?*options*...? + + This command creates a new data source object with an associated Tcl command + whose name is *objectName*. This *[object](../../../../index.md#object)* + command is explained in full detail in the sections [Object + command](#subsection2) and [Object methods](#subsection3). The set of + supported *options* is explained in section [Options](#subsection4). + + The object command will be created under the current namespace if the + *objectName* is not fully qualified, and in the specified namespace + otherwise. The fully qualified name of the object command is returned as the + result of the command. + +## Object command + +All objects created by the __::transfer::data::source__ command have the +following general form: + + - *objectName* __method__ ?*arg arg ...*? + + The method __method__ and its *arg*'uments determine the exact behavior of + the command. See section [Object methods](#subsection3) for the detailed + specifications. + +## Object methods + + - *objectName* __destroy__ + + This method destroys the object. Doing so while a transfer initiated by the + object is active is safe as all data required for the transfer itself was + copied, and the completion of the transfer will not try to access the + initiating object anymore. i.e. the transfer is completely separate from the + source object itself. + + - *objectName* __type__ + + This method returns a string describing the type of the data the object is + refering to. The possible values and their meanings are: + + * __undefined__ + + No data was specified at all, or it was specified incompletely. The + object does not know the type. + + * __string__ + + The data to transfer is contained in a string. + + * __channel__ + + The data to transfer is contained in a channel. + + - *objectName* __data__ + + This method returns a value depending on the type of the data the object + refers to, through which the data can be accessed. The method throws an + error if the type is __undefined__. For type __string__ the returned result + is the data itself, whereas for type __channel__ the returned result is the + handle of the channel containing the data. + + - *objectName* __size__ + + This method returns a value depending on the type of the data the object + refers to, the size of the data. The method throws an error if the type is + __undefined__. Return of a negative value signals that the object is unable + to determine an absolute size upfront (like for data in a channel). + + - *objectName* __valid__ *msgvar* + + This method checks the configuration of the object for validity. It returns + a boolean flag as result, whose value is __True__ if the object is valid, + and __False__ otherwise. In the latter case the variable whose name is + stored in *msgvar* is set to an error message describing the problem found + with the configuration. Otherwise this variable is not touched. + + - *objectName* __transmit__ *channel* *blocksize* *done* + + This method initiates a transfer of the referenced data to the specified + *channel*. When the transfer completes the command prefix *done* is invoked, + per the rules for the option __-command__ of command __transfer::copy::do__ + in the package __[transfer::copy](copyops.md)__. The *blocksize* specifies + the size of the chunks to transfer in one go. See the option __-blocksize__ + of command __transfer::copy::do__ in the package + __[transfer::copy](copyops.md)__. + +## Options + +All data sources support the options listed below. It should be noted that the +first four options are semi-exclusive, each specifying a different type of data +source and associated content. If these options are specified more than once +then the last option specified is used to actually configure the object. + + - __-string__ *text* + + This option specifies that the source of the data is an immediate string, + and its associated argument contains the string in question. + + - __-channel__ *handle* + + This option specifies that the source of the data is a channel, and its + associated argument is the handle of the channel containing the data. + + - __-file__ *path* + + This option specifies that the source of the data is a file, and its + associated argument is the path of the file containing the data. + + - __-variable__ *varname* + + This option specifies that the source of the data is a string stored in a + variable, and its associated argument contains the name of the variable in + question. The variable is assumed to be global or namespaced, anchored at + the global namespace. + + - __-size__ *int* + + This option specifies the size of the data transfer. It is optional and + defaults to -1. This value, and any other value less than zero signals to + transfer all the data from the source. + + - __-progress__ *command* + + This option, if specified, defines a command to be invoked for each chunk of + bytes transmitted, allowing the user to monitor the progress of the + transmission of the data. The callback is always invoked with one additional + argument, the number of bytes transmitted so far. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *transfer* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel](../../../../index.md#channel), [copy](../../../../index.md#copy), +[data source](../../../../index.md#data_source), +[transfer](../../../../index.md#transfer) + +# CATEGORY + +Transfer module + +# COPYRIGHT + +Copyright © 2006-2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/transfer/receiver.md Index: embedded/md/tcllib/files/modules/transfer/receiver.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/transfer/receiver.md @@ -0,0 +1,321 @@ + +[//000000001]: # (transfer::receiver - Data transfer facilities) +[//000000002]: # (Generated from file 'receiver.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (transfer::receiver(n) 0.2 tcllib "Data transfer facilities") + +# NAME + +transfer::receiver - Data source + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Package commands](#subsection1) + + - [Object command](#subsection2) + + - [Object methods](#subsection3) + + - [Options](#subsection4) + + - [Secure connections](#section3) + + - [TLS Security Considerations](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require snit ?1.0? +package require transfer::data::destination ?0.2? +package require transfer::connect ?0.2? +package require transfer::receiver ?0.2? + +[__transfer::receiver__ *object* ?*options*...?](#1) +[__transfer::receiver__ __stream channel__ *chan* *host* *port* ?*arg*...?](#2) +[__transfer::receiver__ __stream file__ *path* *host* *port* ?*arg*...?](#3) +[*objectName* __method__ ?*arg arg ...*?](#4) +[*objectName* __destroy__](#5) +[*objectName* __start__](#6) +[*objectName* __busy__](#7) + +# DESCRIPTION + +This package pulls data destinations and connection setup together into a +combined object for the reception of information coming in over a socket. These +objects understand all the options from objects created by the packages +__[transfer::data::destination](ddest.md)__ and +__[transfer::connect](connect.md)__. + +# API + +## Package commands + + - __transfer::receiver__ *object* ?*options*...? + + This command creates a new receiver object with an associated Tcl command + whose name is *objectName*. This *[object](../../../../index.md#object)* + command is explained in full detail in the sections [Object + command](#subsection2) and [Object methods](#subsection3). The set of + supported *options* is explained in section [Options](#subsection4). + + The object command will be created under the current namespace if the + *objectName* is not fully qualified, and in the specified namespace + otherwise. The fully qualified name of the object command is returned as the + result of the command. + + - __transfer::receiver__ __stream channel__ *chan* *host* *port* ?*arg*...? + + This method creates a fire-and-forget transfer for the data coming from the + source at host/port (details below) and writing to the channel *chan*, + starting at the current seek location. The channel is configured to use + binary translation and encoding for the transfer. The channel is *not* + closed when the transfer has completed. This is left to the completion + callback. + + If both *host* and *port* are provided an __active__ connection to the data + source is made. If only a *port* is specified (with *host* the empty string) + then a __passive__ connection is made instead, i.e. the receiver then waits + for a conneciton by the transmitter. + + Any arguments after the port are treated as options and are used to + configure the internal receiver object. See the section + [Options](#subsection4) for a list of the supported options and their + meaning. *Note* however that the signature of the command prefix specified + for the __-command__ callback differs from the signature for the same option + of the receiver object. This callback is only given the number of bytes and + transfered, and possibly an error message. No reference to the internally + used receiver object is made. + + The result returned by the command is the empty string if it was set to make + an *[active](../../../../index.md#active)* connection, and the port the + internal receiver object is listening on otherwise, i.e when it is + configured to connect *[passive](../../../../index.md#passive)*ly. See also + the package __[transfer::connect](connect.md)__ and the description of the + method __connect__ for where this behaviour comes from. + + - __transfer::receiver__ __stream file__ *path* *host* *port* ?*arg*...? + + This method is like __stream channel__, except that the received data is + written to the file *path*, replacing any prior content. + +## Object command + +All objects created by the __::transfer::receiver__ command have the following +general form: + + - *objectName* __method__ ?*arg arg ...*? + + The method __method__ and its *arg*'uments determine the exact behavior of + the command. See section [Object methods](#subsection3) for the detailed + specifications. + +## Object methods + + - *objectName* __destroy__ + + This method destroys the object. Doing so while a reception is on progress + will cause errors later on, when the reception completes and tries to access + the now missing data structures of the destroyed object. + + - *objectName* __start__ + + This method initiates the data reception, setting up the connection first + and then copying the received information into the destination. The method + will throw an error if a reception is already/still in progress. I.e. it is + not possible to run two receptions in parallel, only in sequence. Errors + will also be thrown if the configuration of the data destination is invalid, + or if no completion callback was specified. + + The result returned by the method is the empty string for an object + configured to make an *[active](../../../../index.md#active)* connection, + and the port the object is listening on otherwise, i.e when it is configured + to connect *[passive](../../../../index.md#passive)*ly. See also the package + __[transfer::connect](connect.md)__ and the description of the method + __connect__ for where this behaviour comes from. + + - *objectName* __busy__ + + This method returns a boolean value telling us whether a reception is in + progress (__True__), or not (__False__). + +## Options + +All receiver objects support the union of the options supported by their connect +and data destination components, plus one of their own. See also the +documentation for the packages __[transfer::data::destination](ddest.md)__ and +__[transfer::connect](connect.md)__. + + - __-command__ *cmdprefix* + + This option specifies the command to invoke when the reception of the + information has been completed. The arguments given to this command are the + same as given to the completion callback of the command + __transfer::copy::do__ provided by the package + __[transfer::copy](copyops.md)__. + + - __-mode__ *mode* + + This option specifies the mode the object is in. It is optional and defaults + to __active__ mode. The two possible modes are: + + * __active__ + + In this mode the two options __-host__ and __-port__ are relevant and + specify the host and TCP port the object has to connect to. The host is + given by either name or IP address. + + * __passive__ + + In this mode the option __-host__ has no relevance and is ignored should + it be configured. The only option the object needs is __-port__, and it + specifies the TCP port on which the listening socket is opened to await + the connection from the partner. + + - __-host__ *hostname-or-ipaddr* + + This option specifies the host to connect to in + *[active](../../../../index.md#active)* mode, either by name or ip-address. + An object configured for *[passive](../../../../index.md#passive)* mode + ignores this option. + + - __-port__ *int* + + For *[active](../../../../index.md#active)* mode this option specifies the + port the object is expected to connect to. For + *[passive](../../../../index.md#passive)* mode however it is the port where + the object creates the listening socket waiting for a connection. It + defaults to __0__, which allows the OS to choose the actual port to listen + on. + + - __-socketcmd__ *command* + + This option allows the user to specify which command to use to open a + socket. The default is to use the builtin __::socket__. Any compatible with + that command is allowed. + + The envisioned main use is the specfication of __tls::socket__. I.e. this + option allows the creation of secure transfer channels, without making this + package explicitly dependent on the __[tls](../../../../index.md#tls)__ + package. + + See also section [Secure connections](#section3). + + - __-encoding__ encodingname + + - __-eofchar__ eofspec + + - __-translation__ transspec + + These options are the same as are recognized by the builtin command + __fconfigure__. They provide the configuration to be set for the channel + between the two partners after it has been established, but before the + callback is invoked (See method __connect__). + + - __-channel__ *handle* + + This option specifies that the destination of the data is a channel, and its + associated argument is the handle of the channel to write the received data + to. + + - __-file__ *path* + + This option specifies that the destination of the data is a file, and its + associated argument is the path of the file to write the received data to. + + - __-variable__ *varname* + + This option specifies that the destination of the data is a variable, and + its associated argument contains the name of the variable to write the + received data to. The variable is assumed to be global or namespaced, + anchored at the global namespace. + + - __-progress__ *command* + + This option, if specified, defines a command to be invoked for each chunk of + bytes received, allowing the user to monitor the progress of the reception + of the data. The callback is always invoked with one additional argument, + the number of bytes received so far. + +# Secure connections + +One way to secure connections made by objects of this package is to require the +package __[tls](../../../../index.md#tls)__ and then configure the option +__-socketcmd__ to force the use of command __tls::socket__ to open the socket. + + # Load and initialize tls + package require tls + tls::init -cafile /path/to/ca/cert -keyfile ... + + # Create a connector with secure socket setup, + transfer::receiver R -socketcmd tls::socket ... + ... + +# TLS Security Considerations + +This package uses the __[TLS](../../../../index.md#tls)__ package to handle the +security for __https__ urls and other socket connections. + +Policy decisions like the set of protocols to support and what ciphers to use +are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this +package itself however. Such decisions are the responsibility of whichever +application is using the package, and are likely influenced by the set of +servers the application will talk to as well. + +For example, in light of the recent [POODLE +attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html) +discovered by Google many servers will disable support for the SSLv3 protocol. +To handle this change the applications using __[TLS](../../../../index.md#tls)__ +must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__ +itself. Such a patch may be as simple as generally activating __tls1__ support, +as shown in the example below. + + package require tls + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol + + ... your own application code ... + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *transfer* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel](../../../../index.md#channel), [copy](../../../../index.md#copy), +[data destination](../../../../index.md#data_destination), +[receiver](../../../../index.md#receiver), +[secure](../../../../index.md#secure), [ssl](../../../../index.md#ssl), +[tls](../../../../index.md#tls), [transfer](../../../../index.md#transfer) + +# CATEGORY + +Transfer module + +# COPYRIGHT + +Copyright © 2006 Andreas Kupries ADDED embedded/md/tcllib/files/modules/transfer/tqueue.md Index: embedded/md/tcllib/files/modules/transfer/tqueue.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/transfer/tqueue.md @@ -0,0 +1,188 @@ + +[//000000001]: # (transfer::copy::queue - Data transfer facilities) +[//000000002]: # (Generated from file 'tqueue.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (transfer::copy::queue(n) 0.1 tcllib "Data transfer facilities") + +# NAME + +transfer::copy::queue - Queued transfers + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Package commands](#subsection1) + + - [Object command](#subsection2) + + - [Object methods](#subsection3) + + - [Options](#section3) + + - [Use](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require snit ?1.0? +package require struct::queue ?1.4? +package require transfer::copy ?0.2? +package require transfer::copy::queue ?0.1? + +[__transfer::copy::queue__ *objectName* *outchannel* ?*options*...?](#1) +[*objectName* __method__ ?*arg arg ...*?](#2) +[*objectName* __destroy__](#3) +[*objectName* __busy__](#4) +[*objectName* __pending__](#5) +[*objectName* __put__ *request*](#6) + +# DESCRIPTION + +This package provides objects which serialize transfer requests for a single +channel by means of a fifo queue. Accumulated requests are executed in order of +entrance, with the first request reaching an idle object starting the execution +in general. New requests can be added while the object is active and are defered +until all requests entered before them have been completed successfully. + +When a request causes a transfer error execution stops and all requests coming +after it are not served. Currently this means that their completion callbacks +are never triggered at all. + +*NOTE*: Not triggering the completion callbacks of the unserved requests after +an error stops the queue object is something I am not fully sure that it makes +sense. It forces the user of the queue to remember the callbacks as well and run +them. Because otherwise everything in the system which depends on getting a +notification about the status of a request will hang in the air. I am slowly +convincing myself that it is more sensible to trigger the relevant completion +callbacks with an error message about the queue abort, and 0 bytes transfered. + +All transfer requests are of the form + + {type data options...} + +where *type* is in {__chan__, __string__}, and *data* specifies the information +to transfer. For __chan__ the data is the handle of the channel containing the +actual information to transfer, whereas for __string__ *data* contains directly +the information to transfer. The *options* are a list of them and their values, +and are the same as are accepted by the low-level copy operations of the package +__[transfer::copy](copyops.md)__. Note how just prepending the request with +__transfer::copy::do__ and inserting a channel handle in between *data* and +*options* easily transforms it from a pure data structure into a command whose +evaluation will perform the request. + +# API + +## Package commands + + - __transfer::copy::queue__ *objectName* *outchannel* ?*options*...? + + This command creates a new queue object for the management of the channel + *outchannel*, with an associated Tcl command whose name is *objectName*. + This *[object](../../../../index.md#object)* command is explained in full + detail in the sections [Object command](#subsection2) and [Object + methods](#subsection3). The set of supported *options* is explained in + section [Options](#section3). + + The object command will be created under the current namespace if the + *objectName* is not fully qualified, and in the specified namespace + otherwise. The fully qualified name of the object command is returned as the + result of the command. + +## Object command + +All objects created by the __::transfer::copy::queue__ command have the +following general form: + + - *objectName* __method__ ?*arg arg ...*? + + The method __method__ and its *arg*'uments determine the exact behavior of + the command. See section [Object methods](#subsection3) for the detailed + specifications. + +## Object methods + + - *objectName* __destroy__ + + This method destroys the object. Doing so while the object is busy will + cause errors later on, when the currently executed request completes and + tries to access the now missing data structures of the destroyed object. + + - *objectName* __busy__ + + This method returns a boolean value telling us if the object is currently + serving a request (i.e. *busy*, value __True__), or not (i.e. + *[idle](../../../../index.md#idle)*, value __False__). + + - *objectName* __pending__ + + This method returns the number of requests currently waiting in the queue + for their execution. A request currently served is not counted as waiting. + + - *objectName* __put__ *request* + + This method enters the transfer *request* into the object's queue of waiting + requests. If the object is *[idle](../../../../index.md#idle)* it will + become *busy*, immediately servicing the request. Otherwise servicing the + new request will be defered until all preceding requests have been served. + +# Options + +The only option known is __-on-status-change__. It is optional and defaults to +the empty list, disabling the reporting of status changes. Otherwise its +argument is a command prefix which is invoked whenever the internal status of +the object changed. The callback is invoked with two additional arguments, the +result of the methods __pending__ and __busy__, in this order. This allows any +user to easily know, for example, when the object has processed all outstanding +requests. + +# Use + +A possible application of this package and class is within a HTTP 1.1 server, +managing the results waiting for transfer to the client. + +It should be noted that in this application the system also needs an additional +data structure which keeps track of outstanding results as they may come back in +a different order than the requests from the client, and releases them to the +actual queue in the proper order. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *transfer* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel](../../../../index.md#channel), [copy](../../../../index.md#copy), +[queue](../../../../index.md#queue), [transfer](../../../../index.md#transfer) + +# CATEGORY + +Transfer module + +# COPYRIGHT + +Copyright © 2006 Andreas Kupries ADDED embedded/md/tcllib/files/modules/transfer/transmitter.md Index: embedded/md/tcllib/files/modules/transfer/transmitter.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/transfer/transmitter.md @@ -0,0 +1,335 @@ + +[//000000001]: # (transfer::transmitter - Data transfer facilities) +[//000000002]: # (Generated from file 'transmitter.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (transfer::transmitter(n) 0.2 tcllib "Data transfer facilities") + +# NAME + +transfer::transmitter - Data source + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Package commands](#subsection1) + + - [Object command](#subsection2) + + - [Object methods](#subsection3) + + - [Options](#subsection4) + + - [Secure connections](#section3) + + - [TLS Security Considerations](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require snit ?1.0? +package require transfer::copy ?0.2? +package require transfer::data::source ?0.2? +package require transfer::connect ?0.2? +package require transfer::transmitter ?0.2? + +[__transfer::transmitter__ *objectName* ?*options*...?](#1) +[__transfer::transmitter__ __stream channel__ *chan* *host* *port* ?*arg*...?](#2) +[__transfer::transmitter__ __stream file__ *path* *host* *port* ?*arg*...?](#3) +[*objectName* __method__ ?*arg arg ...*?](#4) +[*objectName* __destroy__](#5) +[*objectName* __start__](#6) +[*objectName* __busy__](#7) + +# DESCRIPTION + +This package pulls data sources and connection setup together into a combined +object for the transmission of information over a socket. These objects +understand all the options from objects created by the packages +__[transfer::data::source](dsource.md)__ and +__[transfer::connect](connect.md)__. + +# API + +## Package commands + + - __transfer::transmitter__ *objectName* ?*options*...? + + This command creates a new transmitter object with an associated Tcl command + whose name is *objectName*. This *[object](../../../../index.md#object)* + command is explained in full detail in the sections [Object + command](#subsection2) and [Object methods](#subsection3). The set of + supported *options* is explained in section [Options](#subsection4). + + The object command will be created under the current namespace if the + *objectName* is not fully qualified, and in the specified namespace + otherwise. The fully qualified name of the object command is returned as the + result of the command. + + - __transfer::transmitter__ __stream channel__ *chan* *host* *port* ?*arg*...? + + This method creates a fire-and-forget transfer for the data contained in the + channel *chan*, starting at the current seek location. The channel is + configured to use binary translation and encoding for the transfer. The + channel is automatically closed when the transfer has completed. + + If both *host* and *port* are provided an __active__ connection to the + destination is made. If only a *port* is specified (with *host* the empty + string) then a __passive__ connection is made instead. + + Any arguments after the port are treated as options and are used to + configure the internal transmitter object. See the section + [Options](#subsection4) for a list of the supported options and their + meaning. *Note* however that the signature of the command prefix specified + for the __-command__ callback differs from the signature for the same option + of the transmitter object. This callback is only given the number of bytes + and transfered, and possibly an error message. No reference to the + internally used transmitter object is made. + + The result returned by the command is the empty string if it was set to make + an *[active](../../../../index.md#active)* connection, and the port the + internal transmitter object is listening on otherwise, i.e when it is + configured to connect *[passive](../../../../index.md#passive)*ly. See also + the package __[transfer::connect](connect.md)__ and the description of the + method __connect__ for where this behaviour comes from. + + - __transfer::transmitter__ __stream file__ *path* *host* *port* ?*arg*...? + + This method is like __stream channel__, except that the data contained in + the file *path* is transfered. + +## Object command + +All objects created by the __::transfer::transmitter__ command have the +following general form: + + - *objectName* __method__ ?*arg arg ...*? + + The method __method__ and its *arg*'uments determine the exact behavior of + the command. See section [Object methods](#subsection3) for the detailed + specifications. + +## Object methods + + - *objectName* __destroy__ + + This method destroys the object. Doing so while a transmission is in + progress will cause errors later on, when the transmission completes and + tries to access the now missing data structures of the destroyed object. + + - *objectName* __start__ + + This method initiates the data transmission, setting up the connection first + and then copying the information. The method will throw an error if a + transmission is already/still in progress. I.e. it is not possible to run + two transmissions in parallel on a single object, only in sequence. Multiple + transmitter objects are needed to manage parallel transfers, one per + transmission. Errors will also be thrown if the configuration of the data + source is invalid, or if no completion callback was specified. + + The result returned by the method is the empty string for an object + configured to make an *[active](../../../../index.md#active)* connection, + and the port the object is listening on otherwise, i.e when it is configured + to connect *[passive](../../../../index.md#passive)*ly. See also the package + __[transfer::connect](connect.md)__ and the description of the method + __connect__ for where this behaviour comes from. + + - *objectName* __busy__ + + This method returns a boolean value telling us whether a transmission is in + progress (__True__), or not (__False__). + +## Options + +All transmitter objects support the union of the options supported by their +connect and data source components, plus two of their own. See also the +documentation for the packages __[transfer::data::source](dsource.md)__ and +__[transfer::connect](connect.md)__. + + - __-blocksize__ *int* + + This option specifies the size of the chunks to be transmitted in one block. + Usage is optional, its default value is __1024__. + + - __-command__ *cmdprefix* + + This option specifies the command to invoke when the transmission of the + information has been completed. The arguments given to this command are the + same as given to the completion callback of the command + __transfer::copy::do__ provided by the package + __[transfer::copy](copyops.md)__. + + - __-mode__ *mode* + + This option specifies the mode the object is in. It is optional and defaults + to __active__ mode. The two possible modes are: + + * __active__ + + In this mode the two options __-host__ and __-port__ are relevant and + specify the host and TCP port the object has to connect to. The host is + given by either name or IP address. + + * __passive__ + + In this mode the option __-host__ has no relevance and is ignored should + it be configured. The only option the object needs is __-port__, and it + specifies the TCP port on which the listening socket is opened to await + the connection from the partner. + + - __-host__ *hostname-or-ipaddr* + + This option specifies the host to connect to in + *[active](../../../../index.md#active)* mode, either by name or ip-address. + An object configured for *[passive](../../../../index.md#passive)* mode + ignores this option. + + - __-port__ *int* + + For *[active](../../../../index.md#active)* mode this option specifies the + port the object is expected to connect to. For + *[passive](../../../../index.md#passive)* mode however it is the port where + the object creates the listening socket waiting for a connection. It + defaults to __0__, which allows the OS to choose the actual port to listen + on. + + - __-socketcmd__ *command* + + This option allows the user to specify which command to use to open a + socket. The default is to use the builtin __::socket__. Any compatible with + that command is allowed. + + The envisioned main use is the specfication of __tls::socket__. I.e. this + option allows the creation of secure transfer channels, without making this + package explicitly dependent on the __[tls](../../../../index.md#tls)__ + package. + + See also section [Secure connections](#section3). + + - __-encoding__ encodingname + + - __-eofchar__ eofspec + + - __-translation__ transspec + + These options are the same as are recognized by the builtin command + __fconfigure__. They provide the configuration to be set for the channel + between the two partners after it has been established, but before the + callback is invoked (See method __connect__). + + - __-string__ *text* + + This option specifies that the source of the data is an immediate string, + and its associated argument contains the string in question. + + - __-channel__ *handle* + + This option specifies that the source of the data is a channel, and its + associated argument is the handle of the channel containing the data. + + - __-file__ *path* + + This option specifies that the source of the data is a file, and its + associated argument is the path of the file containing the data. + + - __-variable__ *varname* + + This option specifies that the source of the data is a string stored in a + variable, and its associated argument contains the name of the variable in + question. The variable is assumed to be global or namespaced, anchored at + the global namespace. + + - __-size__ *int* + + This option specifies the size of the data transfer. It is optional and + defaults to -1. This value, and any other value less than zero signals to + transfer all the data from the source. + + - __-progress__ *command* + + This option, if specified, defines a command to be invoked for each chunk of + bytes transmitted, allowing the user to monitor the progress of the + transmission of the data. The callback is always invoked with one additional + argument, the number of bytes transmitted so far. + +# Secure connections + +One way to secure connections made by objects of this package is to require the +package __[tls](../../../../index.md#tls)__ and then configure the option +__-socketcmd__ to force the use of command __tls::socket__ to open the socket. + + # Load and initialize tls + package require tls + tls::init -cafile /path/to/ca/cert -keyfile ... + + # Create a connector with secure socket setup, + transfer::transmitter T -socketcmd tls::socket ... + ... + +# TLS Security Considerations + +This package uses the __[TLS](../../../../index.md#tls)__ package to handle the +security for __https__ urls and other socket connections. + +Policy decisions like the set of protocols to support and what ciphers to use +are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this +package itself however. Such decisions are the responsibility of whichever +application is using the package, and are likely influenced by the set of +servers the application will talk to as well. + +For example, in light of the recent [POODLE +attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html) +discovered by Google many servers will disable support for the SSLv3 protocol. +To handle this change the applications using __[TLS](../../../../index.md#tls)__ +must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__ +itself. Such a patch may be as simple as generally activating __tls1__ support, +as shown in the example below. + + package require tls + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol + + ... your own application code ... + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *transfer* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel](../../../../index.md#channel), [copy](../../../../index.md#copy), +[data source](../../../../index.md#data_source), +[secure](../../../../index.md#secure), [ssl](../../../../index.md#ssl), +[tls](../../../../index.md#tls), [transfer](../../../../index.md#transfer), +[transmitter](../../../../index.md#transmitter) + +# CATEGORY + +Transfer module + +# COPYRIGHT + +Copyright © 2006-2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/treeql/treeql.md Index: embedded/md/tcllib/files/modules/treeql/treeql.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/treeql/treeql.md @@ -0,0 +1,682 @@ + +[//000000001]: # (treeql - Tree Query Language) +[//000000002]: # (Generated from file 'treeql.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (treeql(n) 1.3.1 tcllib "Tree Query Language") + +# NAME + +treeql - Query tree objects + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [TreeQL CLASS API](#subsection1) + + - [TreeQL OBJECT API](#subsection2) + + - [The Tree Query Language](#section3) + + - [TreeQL Concepts](#subsection3) + + - [Structural generators](#subsection4) + + - [Attribute Filters](#subsection5) + + - [Attribute Mutators](#subsection6) + + - [Attribute String Accessors](#subsection7) + + - [Sub-queries](#subsection8) + + - [Node Set Operators](#subsection9) + + - [Node Set Iterators](#subsection10) + + - [Typed node support](#subsection11) + + - [Examples](#section4) + + - [References](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.2 +package require snit +package require struct::list +package require struct::set +package require treeql ?1.3.1? + +[__treeql__ *objectname* __-tree__ *tree* ?__-query__ *query*? ?__-nodes__ *nodes*? ?*args*...?](#1) +[*qo* __query__ *args*...](#2) +[*qo* __result__](#3) +[*qo* __discard__](#4) + +# DESCRIPTION + +This package provides objects which can be used to query and transform tree +objects following the API of tree objects created by the package +__[struct::tree](../struct/struct_tree.md)__. + +The tree query and manipulation language used here, TreeQL, is inspired by Cost +(See section [References](#section5) for more information). + +__treeql__, the package, is a fairly thin query facility over tree-structured +data types. It implements an ordered set of nodes (really a list) which are +generated and filtered through the application of TreeQL operators to each node +in turn. + +# API + +## TreeQL CLASS API + +The command __treeql__ is a __[snit](../snit/snit.md)__::type which implements +the Treeql Query Language. This means that it follows the API for class commands +as specified by the package __[snit](../snit/snit.md)__. Its general syntax is + + - __treeql__ *objectname* __-tree__ *tree* ?__-query__ *query*? ?__-nodes__ *nodes*? ?*args*...? + + The command creates a new tree query object and returns the fully qualified + name of the object command as its result. The API the returned command is + following is described in the section [TreeQL OBJECT API](#subsection2) + + Each query object is associated with a single *tree* object. This is the + object all queries will be run against. + + If the option __-nodes__ was specified then its argument is treated as a + list of nodes. This list is used to initialize the node set. It defaults to + the empty list. + + If the option __-query__ was specified then its argument will be interpreted + as an object, the *parent query* of this query. It defaults to the object + itself. All queries will be interpreted in the environment of this object. + + Any arguments coming after the options are treated as a query and run + immediately, after the *node set* has been initialized. This uses the same + syntax for the query as the method __query__. + + The operations of the TreeQL available for this are explained in the section + about [The Tree Query Language](#section3). This section also explains the + term *node set* used above. + +## TreeQL OBJECT API + +As __treeql__ has been implemented in __[snit](../snit/snit.md)__ all the +standard methods of __[snit](../snit/snit.md)__-based classes are available to +the user and therefore not listed here. Please read the documentation for +__[snit](../snit/snit.md)__ for what they are and what functionality they +provide + +The methods provided by the package __treeql__ itself are listed and explained +below. + + - *qo* __query__ *args*... + + This method interprets its arguments as a series of TreeQL operators and + interpretes them from the left to right (i.e. first to last). Note that the + first operator uses the *node set* currently known to the object to perform + its actions. In other words, the *node set* is *not* cleared, or modified in + other ways, before the query is run. This allows the user to run several + queries one after the other and have each use the results of the last. Any + initialization has to be done by any query itself, using TreeQL operators. + The result of the method is the *node set* after the last operator of the + query has been executed. + + *Note* that uncaught errors will leave the *node set* of the object in an + intermediate state, per the TreeQL operators which were executed + successfully before the error occurred. + + The above means in detail that: + + The first argument is interpreted as the name of a query operator, the + number of arguments required by that operator is then determined, and taken + from the immediately following arguments. + + Because of this operators cannot have optional arguments, all arguments have + to be present as defined. Failure to do this will, at least, confuse the + query interpreter, but more likely cause errors. + + The operator is applied to the current node set, yielding a new node set, + and/or manipulating the tree object the query object is connected to. + + The arguments used (i.e. operator name and arguments) are removed from the + list of method arguments, and then the whole process is repeated from step + [1], until the list of arguments is empty or an error occurred. + + # q is the query object. + + q query root children get data + + # The above query + # - Resets the node set to the root node - root + # - Adds the children of root to the set - children + # - Replaces the node set with the - get data + # values for the attribute 'data', + # for all nodes in the set which + # have such an attribute. + # - And returns this information. + + # Below we can see the same query, but rewritten + # to show the structure as it is seen by the query + # interpreter. + + q query \\ + root \\ + children \\ + get data + + The operators of the TreeQL language available for this are explained in the + section about [The Tree Query Language](#section3). This section also + explains the term *node set* used above. + + - *qo* __result__ + + This method returns a list containing the current node set. + + - *qo* __discard__ + + This method returns the current node set (like method __result__), but also + destroys the query object (*qo*). This is useful when constructing and using + sub-queries (%AUTO% objects immediately destroyed after use). + +# The Tree Query Language + +This and the following sections specify the Tree Query Language used by the +query objects of this package in detail. + +First we explain the general concepts underneath the language which are required +to comprehend it. This is followed by the specifications for all the available +query operators. They fall into eight categories, and each category has its own +section. + + 1. [TreeQL Concepts](#subsection3) + + 1. [Structural generators](#subsection4) + + 1. [Attribute Filters](#subsection5) + + 1. [Attribute Mutators](#subsection6) + + 1. [Attribute String Accessors](#subsection7) + + 1. [Sub-queries](#subsection8) + + 1. [Node Set Operators](#subsection9) + + 1. [Node Set Iterators](#subsection10) + + 1. [Typed node support](#subsection11) + +## TreeQL Concepts + +The main concept which has to be understood is that of the *node set*. Each +query object maintains exactly one such *node set*, and essentially all +operators use it and input argument and for their result. This structure simply +contains the handles of all nodes which are currently of interest to the query +object. To name it a *[set](../../../../index.md#set)* is a bit of a misnomer, +because + + 1. A node (handle) can occur in the structure more than once, and + + 1. the order of nodes in the structure is important as well. Whenever an + operator processes all nodes in the node set it will do so in the order + they occur in the structure. + +Regarding the possible multiple occurrence of a node, consider a node set +containing two nodes A and B, both having node P as their immediate parent. +Application of the TreeQL operator "parent" will then add P to the new node set +twice, once per node it was parent of. I.e. the new node set will then be {P P}. + +## Structural generators + +All tree-structural operators locate nodes in the tree based on a structural +relation ship to the nodes currently in the set and then replace the current +node set with the set of nodes found Nodes which fulfill such a relationship +multiple times are added to the result as often as they fulfill the +relationship. + +It is important to note that the found nodes are collected in a separate storage +area while processing the node set, and are added to (or replacing) the current +node set only after the current node set has been processed completely. In other +words, the new nodes are *not* processed by the operator as well and do not +affect the iteration. + +When describing an operator the variable __N__ will be used to refer to any node +in the node set. + + - __ancestors__ + + Replaces the current node set with the ancestors for all nodes __N__ in the + node set, should __N__ have a parent. In other words, nodes without a parent + do not contribute to the new node set. In other words, uses all nodes on the + path from node __N__ to root, in this order (root last), for all nodes __N__ + in the node set. This includes the root, but not the node itself. + + - __rootpath__ + + Replaces the current node set with the ancestors for all nodes __N__ in the + node set, should __N__ have a parent. In other words, nodes without a parent + do not contribute to the new node set. In contrast to the operator + __ancestors__ the nodes are added in reverse order however, i.e. the root + node first. + + - __parent__ + + Replaces the current node set with the parent of node __N__, for all nodes + __N__ in the node set, should __N__ have a parent. In other words, nodes + without a parent do not contribute to the new node set. + + - __children__ + + Replaces the current node set with the immediate children of node __N__, for + all nodes __N__ in the node set, should __N__ have children. In other words, + nodes without children do not contribute to the new node set. + + - __left__ + + Replaces the current node set with the previous/left sibling for all nodes + __N__ in the node set, should __N__ have siblings to the left. In other + words, nodes without left siblings do not contribute to the new node set. + + - __right__ + + Replaces the current node set with the next/right sibling for all nodes + __N__ in the node set, should __N__ have siblings to the right. In other + words, nodes without right siblings do not contribute to the new node set. + + - __prev__ + + Replaces the current node set with all previous/left siblings of node __N__, + for all nodes __N__ in the node set, should __N__ have siblings to the left. + In other words, nodes without left siblings are ignored. The left sibling + adjacent to the node is added first, and the leftmost sibling last (reverse + tree order). + + - __esib__ + + Replaces the current node set with all previous/left siblings of node __N__, + for all nodes __N__ in the node set, should __N__ have siblings to the left. + In other words, nodes without left siblings are ignored. The leftmost + sibling is added first, and the left sibling adjacent to the node last (tree + order). + + The method name is a shorthand for *Earlier SIBling*. + + - __next__ + + Replaces the current node set with all next/right siblings of node __N__, + for all nodes __N__ in the node set, should __N__ have siblings to the + right. In other words, nodes without right siblings do not contribute to the + new node set. The right sibling adjacent to the node is added first, and the + rightmost sibling last (tree order). + + - __root__ + + Replaces the current node set with a node set containing a single node, the + root of the tree. + + - __tree__ + + Replaces the current node set with a node set containing all nodes found in + the tree. The nodes are added in pre-order (parent first, then children, the + latter from left to right, first to last). + + - __descendants__ + + Replaces the current node set with the nodes in all subtrees rooted at node + __N__, for all nodes __N__ in the node set, should __N__ have children. In + other words, nodes without children do not contribute to the new node set. + + This is like the operator __children__, but covers the children of children + as well, i.e. all the *proper descendants*. "Rooted at __N__" means that + __N__ itself is not added to the new set, which is also implied by *proper + descendants*. + + - __subtree__ + + Like operator __descendants__, but includes the node __N__. In other words: + + Replaces the current node set with the nodes of the subtree of node __N__, + for all nodes __N__ in the node set, should __N__ have children. In other + words, nodes without children do not contribute to the new node set. I.e + this is like the operator __children__, but covers the children of children, + etc. as well. "Of __N__" means that __N__ itself is added to the new set. + + - __forward__ + + Replaces the current node set with the nodes in the subtrees rooted at the + right siblings of node __N__, for all nodes __N__ in the node set, should + __N__ have right siblings, and they children. In other words, nodes without + right siblings, and them without children are ignored. + + This is equivalent to the operator sequence + + next descendants + + - __later__ + + This is an alias for the operator __forward__. + + - __backward__ + + Replaces the current node set with the nodes in the flattened previous + subtrees, in reverse tree order. + + This is nearly equivalent to the operator sequence + + prev descendants + + The only difference is that this uses the nodes in reverse order. + + - __earlier__ + + Replaces the current node set with the nodes in the flattened previous + subtrees, in tree order. + + This is equivalent to the operator sequence + + prev subtree + +## Attribute Filters + +These operators filter the node set by reference to attributes of nodes and +their properties. Filter means that all nodes not fulfilling the criteria are +removed from the node set. In other words, the node set is replaced by the set +of nodes fulfilling the filter criteria. + + - __hasatt__ *attr* + + Reduces the node set to nodes which have an attribute named *attr*. + + - __withatt__ *attr* *value* + + Reduces the node set to nodes which have an attribute named *attr*, and + where the value of that attribute is equal to *value* (The "==" operator is + __string equal -nocase__). + + - __withatt!__ *attr* *val* + + This is the same as __withatt__, but all nodes in the node set have to have + the attribute, and the "==" operator is __string equal__, i.e. no + __-nocase__. The operator will fail with an error if they don't have the + attribute. + + - __attof__ *attr* *vals* + + Reduces the node set to nodes which which have an attribute named *attr* and + where the value of that attribute is contained in the list *vals* of legal + values. The contained-in operator used here does glob matching (using the + attribute value as pattern) and ignores the case of the attribute value, + *but not* for the elements of *vals*. + + - __attmatch__ *attr* *match* + + Same as __withatt__, but __string match__ is used as the "==" operator, and + *match* is the pattern checked for. + + *Note* that *match* is a interpreted as a partial argument *list* for + __string match__. This means that it is interpreted as a list containing the + pattern, and the pattern element can be preceded by options understand by + __string match__, like __-nocase__. This is especially important should the + pattern contain spaces. It has to be wrapped into a list for correct + interpretation by this operator + +## Attribute Mutators + +These operators change node attributes within the underlying tree. In other +words, all these operators have *side effects*. + + - __set__ *attr* *val* + + Sets the attribute *attr* to the value *val*, for all nodes __N__ in the + node set. The operator will fail if a node does not have an attribute named + *attr*. The tree will be left in a partially modified state. + + - __unset__ *attr* + + Unsets the attribute *attr*, for all nodes __N__ in the node set. The + operator will fail if a node does not have an attribute named *attr*. The + tree will be left in a partially modified state. + +## Attribute String Accessors + +These operators retrieve the values of node attributes from the underlying tree. +The collected results are stored in the node set, but are not actually nodes. + +In other words, they redefine the semantics of the node set stored by the query +object to contain non-node data after their completion. + +The query interpreter will terminate after it has finished processing one of +these operators, silently discarding any later query elements. It also means +that our talk about maintenance of a node set is not quite true. It is a node +set while the interpreter is processing commands, but can be left as an +attribute value set at the end of query processing. + + - __string__ *op* *attr* + + Applies the string operator *op* to the attribute named *attr*, for all + nodes __N__ in the node set, collects the results of that application and + places them into the node set. + + The operator will fail if a node does not have an attribute named *attr*. + + The argument *op* is interpreted as partial argument list for the builtin + command __[string](../../../../index.md#string)__. Its first word has to be + any of the sub-commands understood by + __[string](../../../../index.md#string)__. This has to be followed by all + arguments required for the subcommand, except the last. that last argument + is supplied by the attribute value. + + - __get__ *pattern* + + For all nodes __N__ in the node set it determines all their attributes with + names matching the glob *pattern*, then the values of these attributes, at + last it replaces the node set with the list of these attribute values. + + - __attlist__ + + This is a convenience definition for the operator __getvals *__. In other + words, it replaces the node set with a list of the attribute values for all + attributes for all nodes __N__ in the node set. + + - __attrs__ *glob* + + Replaces the current node set with a list of attribute lists, one attribute + list per for all nodes __N__ in the node set. + + - __attval__ *attname* + + Reduces the current node set with the operator __hasatt__, and then replaces + it with a list containing the values of the attribute named *attname* for + all nodes __N__ in the node set. + +## Sub-queries + +Sub-queries yield node sets which are then used to augment, reduce or replace +the current node set. + + - __andq__ *query* + + Replaces the node set with the set-intersection of the node set generated by + the sub-query *query* and itself. + + The execution of the sub-query uses the current node set as its own initial + node set. + + - __orq__ *query* + + Replaces the node set with the set-union of the node set generated by the + sub-query *query* and itself. Duplicate nodes are removed. + + The execution of the sub-query uses the current node set as its own initial + node set. + + - __notq__ *query* + + Replaces the node set with the set of nodes generated by the sub-query + *query* which are also not in the current node set. In other word the set + difference of itself and the node set generated by the sub-query. + + The execution of the sub-query uses the current node set as its own initial + node set. + +## Node Set Operators + +These operators change the node set directly, without referring to the tree. + + - __unique__ + + Removes duplicate nodes from the node set, preserving order. In other words, + the earliest occurrence of a node handle is preserved, every other + occurrence is removed. + + - __select__ + + Replaces the current node set with a node set containing only the first node + from the current node set + + - __transform__ *query* *var* *body* + + First it interprets the sub-query *query*, using the current node set as its + initial node set. Then it iterates over the result of that query, binding + the handle of each node to the variable named in *var*, and executing the + script *body*. The collected results of these executions is made the new + node set, replacing the current one. + + The script *body* is executed in the context of the caller. + + - __map__ *var* *body* + + Iterates over the current node set, binding the handle of each node to the + variable named in *var*, and executing the script *body*. The collected + results of these executions is made the new node set, replacing the current + one. + + The script *body* is executed in the context of the caller. + + - __quote__ *val* + + Appends the literal value *val* to the current node set. + + - __replace__ *val* + + Replaces the current node set with the literal list value *val*. + +## Node Set Iterators + + - __foreach__ *query* *var* *body* + + Interprets the sub-query *query*, then performs the equivalent of operator + __over__ on the nodes in the node set created by that query. The current + node set is not changed, except through side effects from the script *body*. + + The script *body* is executed in the context of the caller. + + - __with__ *query* *body* + + Interprets the *query*, then runs the script *body* on the node set + generated by the query. At last it restores the current node set as it was + before the execution of the query. + + The script *body* is executed in the context of the caller. + + - __over__ *var* *body* + + Executes the script *body* for each node in the node set, with the variable + named by *var* bound to the name of the current node. The script *body* is + executed in the context of the caller. + + This is like the builtin __[foreach](../../../../index.md#foreach)__, with + the node set as the source of the list to iterate over. + + The results of executing the *body* are ignored. + + - __delete__ + + Deletes all the nodes contained in the current node set from the tree. + +## Typed node support + +These filters and accessors assume the existence of an attribute called +__@type__, and are short-hand forms useful for cost-like tree query, html tree +editing, and so on. + + - __nodetype__ + + Returns the node type of nodes. Attribute string accessor. This is + equivalent to + + get @type + + - __oftype__ *t* + + Reduces the node set to nodes whose type is equal to *t*, with letter case + ignored. + + - __nottype__ *t* + + Reduces the node set to nodes whose type is not equal to *t*, with letter + case ignored. + + - __oftypes__ *attrs* + + Reduces set to nodes whose @type is an element in the list *attrs* of types. + The value of @type is used as a glob pattern, and letter case is relevant. + +# Examples + +... TODO ... + +# References + + 1. [COST](http://wiki.tcl.tk/COST) on the Tcler's Wiki. + + 1. [TreeQL](http://wiki.tcl.tk/treeql) on the Tcler's Wiki. Discuss this + package there. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *treeql* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Cost](../../../../index.md#cost), [DOM](../../../../index.md#dom), +[TreeQL](../../../../index.md#treeql), [XPath](../../../../index.md#xpath), +[XSLT](../../../../index.md#xslt), [structured +queries](../../../../index.md#structured_queries), +[tree](../../../../index.md#tree), [tree query +language](../../../../index.md#tree_query_language) + +# CATEGORY + +Data structures + +# COPYRIGHT + +Copyright © 2004 Colin McCormack +Copyright © 2004 Andreas Kupries ADDED embedded/md/tcllib/files/modules/try/tcllib_throw.md Index: embedded/md/tcllib/files/modules/try/tcllib_throw.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/try/tcllib_throw.md @@ -0,0 +1,82 @@ + +[//000000001]: # (throw - Forward compatibility implementation of [throw]) +[//000000002]: # (Generated from file 'tcllib_throw.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (throw(n) 1 tcllib "Forward compatibility implementation of [throw]") + +# NAME + +throw - throw - Throw an error exception with a message + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [EXAMPLES](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require throw ?1? + +[__::throw__ *error_code* *error_message*](#1) + +# DESCRIPTION + +This package provides a forward-compatibility implementation of Tcl 8.6's throw +command (TIP 329), for Tcl 8.5. The code was directly pulled from Tcl 8.6 +revision ?, when try/finally was implemented as Tcl procedure instead of in C. + + - __::throw__ *error_code* *error_message* + + throw is merely a reordering of the arguments of the error command. It + throws an error with the indicated error code and error message. + +# EXAMPLES + + __throw__ {MYERROR CODE} "My error message" + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *try* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +error(n) + +# KEYWORDS + +[error](../../../../index.md#error), [return](../../../../index.md#return), +[throw](../../../../index.md#throw) + +# CATEGORY + +Utility + +# COPYRIGHT + +Copyright © 2015 Miguel Martínez López, BSD licensed ADDED embedded/md/tcllib/files/modules/try/tcllib_try.md Index: embedded/md/tcllib/files/modules/try/tcllib_try.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/try/tcllib_try.md @@ -0,0 +1,154 @@ + +[//000000001]: # (try - Forward compatibility implementation of [try]) +[//000000002]: # (Generated from file 'tcllib_try.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (try(n) 1 tcllib "Forward compatibility implementation of [try]") + +# NAME + +try - try - Trap and process errors and exceptions + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [EXAMPLES](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require try ?1? + +[__::try__ *body* ?*handler...*? ?__finally__ *script*?](#1) + +# DESCRIPTION + +This package provides a forward-compatibility implementation of Tcl 8.6's +try/finally command (TIP 329), for Tcl 8.5. The code was directly pulled from +Tcl 8.6 revision ?, when try/finally was implemented as Tcl procedure instead of +in C. + + - __::try__ *body* ?*handler...*? ?__finally__ *script*? + + This command executes the script *body* and, depending on what the outcome + of that script is (normal exit, error, or some other exceptional result), + runs a handler script to deal with the case. Once that has all happened, if + the __finally__ clause is present, the *script* it includes will be run and + the result of the handler (or the *body* if no handler matched) is allowed + to continue to propagate. Note that the __finally__ clause is processed even + if an error occurs and irrespective of which, if any, *handler* is used. + + The *handler* clauses are each expressed as several words, and must have one + of the following forms: + + * __on__ *code variableList script* + + This clause matches if the evaluation of *body* completed with the + exception code *code*. The *code* may be expressed as an integer or one + of the following literal words: __ok__, __error__, __return__, + __break__, or __continue__. Those literals correspond to the integers 0 + through 4 respectively. + + * __trap__ *pattern variableList script* + + This clause matches if the evaluation of *body* resulted in an error and + the prefix of the __-errorcode__ from the interpreter's status + dictionary is equal to the *pattern*. The number of prefix words taken + from the __-errorcode__ is equal to the list-length of *pattern*, and + inter-word spaces are normalized in both the __-errorcode__ and + *pattern* before comparison. + + The *variableList* word in each *handler* is always interpreted as a + list of variable names. If the first word of the list is present and + non-empty, it names a variable into which the result of the evaluation + of *body* (from the main __try__) will be placed; this will contain the + human-readable form of any errors. If the second word of the list is + present and non-empty, it names a variable into which the options + dictionary of the interpreter at the moment of completion of execution + of *body* will be placed. + + The *script* word of each *handler* is also always interpreted the same: + as a Tcl script to evaluate if the clause is matched. If *script* is a + literal __-__ and the *handler* is not the last one, the *script* of the + following *handler* is invoked instead (just like with the __switch__ + command). + + Note that *handler* clauses are matched against in order, and that the + first matching one is always selected. At most one *handler* clause will + selected. As a consequence, an __on error__ will mask any subsequent + __trap__ in the __try__. Also note that __on error__ is equivalent to + __trap {}__. + + If an exception (i.e. any non-__ok__ result) occurs during the + evaluation of either the *handler* or the __finally__ clause, the + original exception's status dictionary will be added to the new + exception's status dictionary under the __-during__ key. + +# EXAMPLES + +Ensure that a file is closed no matter what: + + set f [open /some/file/name a] + __try__ { + puts \$f "some message" + # ... + } __finally__ { + close \$f + } + +Handle different reasons for a file to not be openable for reading: + + __try__ { + set f [open /some/file/name] + } __trap__ {POSIX EISDIR} {} { + puts "failed to open /some/file/name: it's a directory" + } __trap__ {POSIX ENOENT} {} { + puts "failed to open /some/file/name: it doesn't exist" + } + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *try* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +catch(n), error(n), return(n), [throw(n)](tcllib_throw.md) + +# KEYWORDS + +[cleanup](../../../../index.md#cleanup), [error](../../../../index.md#error), +[exception](../../../../index.md#exception), +[final](../../../../index.md#final), [resource +management](../../../../index.md#resource_management) + +# CATEGORY + +Utility + +# COPYRIGHT + +Copyright © 2008 Donal K. Fellows, BSD licensed ADDED embedded/md/tcllib/files/modules/udpcluster/udpcluster.md Index: embedded/md/tcllib/files/modules/udpcluster/udpcluster.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/udpcluster/udpcluster.md @@ -0,0 +1,95 @@ + +[//000000001]: # (udpcluster - Lightweight UDP based tool for cluster node discovery) +[//000000002]: # (Generated from file 'udpcluster.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (udpcluster(n) 0.3.3 tcllib "Lightweight UDP based tool for cluster node discovery") + +# NAME + +udpcluster - UDP Peer-to-Peer cluster + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Bugs, Ideas, Feedback](#section2) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require udpcluster ?0.3.3? +package require ip +package require nettool +package require comm +package require interp +package require dicttool +package require cron + +# DESCRIPTION + +This package is a lightweight alternative to Zeroconf. It utilizes UDP packets +to populate a table of services provided by each node on a local network. Each +participant broadcasts a key/value list in plain UTF-8 which lists what ports +are open, and what protocols are expected on those ports. Developers are free to +add any additional key/value pairs beyond those. + +Using udpcluster. + +For every service you wish to publish invoke: + + cluster::publish echo@[cluster::macid] {port 10000 protocol echo} + +To query what services are available on the local network: + + set results [cluster::search PATTERN] + # And inside that result... + echo@LOCALMACID { + port 10000 + protocol echo + } + +To unpublish a service: + + cluster::unpublish echo@[cluster::macid] + +Results will Historical Notes: + +This tool was originally known as nns::cluster, but as development progressed, +it was clear that it wasn't interacting with any of the other facilities in NNS. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *nameserv* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[name service](../../../../index.md#name_service), +[server](../../../../index.md#server) + +# CATEGORY + +Networking + +# COPYRIGHT + +Copyright © 2016-2018 Sean Woods ADDED embedded/md/tcllib/files/modules/uev/uevent.md Index: embedded/md/tcllib/files/modules/uev/uevent.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/uev/uevent.md @@ -0,0 +1,219 @@ + +[//000000001]: # (uevent - User events) +[//000000002]: # (Generated from file 'uevent.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (uevent(n) 0.3.1 tcllib "User events") + +# NAME + +uevent - User events + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require uevent ?0.3.1? +package require logger + +[__::uevent::bind__ *tag* *event* *command*](#1) +[__[command](../../../../index.md#command)__ *tag* *event* *details*](#2) +[__::uevent::unbind__ *token*](#3) +[__::uevent::generate__ *tag* *event* ?*details*?](#4) +[__::uevent::list__](#5) +[__::uevent::list__ *tag*](#6) +[__::uevent::list__ *tag* *event*](#7) +[__::uevent::watch::tag::add__ *pattern* *command*](#8) +[__{*}command__ __bound__ *tag*](#9) +[__{*}command__ __unbound__ *tag*](#10) +[__::uevent::watch::tag::remove__ *token*](#11) +[__::uevent::watch::event::add__ *tag_pattern* *event_pattern* *command*](#12) +[__{*}command__ __bound__ *tag* *event*](#13) +[__{*}command__ __unbound__ *tag* *event*](#14) +[__::uevent::watch::event::remove__ *token*](#15) + +# DESCRIPTION + +This package provides a general facility for the handling of user events. Allows +the binding of arbitrary commands to arbitrary events on arbitrary tags, removal +of bindings, and event generation. + +The main difference to the event system built into the Tcl/Tk core is that the +latter can generate only virtual events, and only for widgets. It is not +possible to use the builtin facilities to bind to events on arbitrary +(pseudo-)objects, nor is it able to generate events for such. + +Here we can, by assuming that each object in question is represented by its own +tag. Which is possible as we allow arbitrary tags. + +More differences: + + 1. The package uses only a two-level hierarchy, tags and events, to handle + everything, whereas the Tcl/Tk system uses three levels, i.e. objects, + tags, and events, with a n:m relationship between objects and tags. + + 1. This package triggers all bound commands for a tag/event combination, and + they are independent of each other. A bound command cannot force the event + processing core to abort the processing of command coming after it. + +# API + +The package exports eight commands, as specified below. Note that when the +package is used from within Tcl 8.5+ all the higher commands are ensembles, i.e. +the :: separators can be replaceed by spaces. + + - __::uevent::bind__ *tag* *event* *command* + + Using this command registers the *command* prefix to be triggered when the + *event* occurs for the *tag*. The result of the command is an opaque token + representing the binding. Note that if the same combination of + <*tag*,*event*,*command*> is used multiple times the same token is returned + by every call. + + The signature of the *command* prefix is + + * __[command](../../../../index.md#command)__ *tag* *event* *details* + + where *details* contains the argument(s) of the event. Its contents are + event specific and have to be agreed upon between actual event generator and + consumer. This package simply transfers the information and does not perform + any processing beyond that. + + - __::uevent::unbind__ *token* + + This command releases the event binding represented by the *token*. The + token has to be the result of a call to __::uevent::bind__. The result of + the command is the empty string. + + - __::uevent::generate__ *tag* *event* ?*details*? + + This command generates an *event* for the *tag*, triggering all commands + bound to that combination. The *details* argument is simply passed unchanged + to all event handlers. It is the responsibility of the code generating and + consuming the event to have an agreement about the format and contents of + the information carried therein. The result of the command is the empty + string. + + Note that all bound commands are triggered, independently of each other. The + event handlers cannot assume a specific order. They are also *not* called + synchronously with the invokation of this command, but simply put into the + event queue for processing when the system returns to the event loop. + + Generating an event for an unknown tag, or for a <*tag*,*event*> combination + which has no commands bound to it is allowed, such calls will be ignored. + + - __::uevent::list__ + + In this form the command returns a list containing the names of all tags + which have events with commands bound to them. + + - __::uevent::list__ *tag* + + In this format the command returns a list containing the names of all events + for the *tag* with commands bound to them. Specifying an unknown tag, i.e. a + tag without event and commands, will cause the command to throw an error. + + - __::uevent::list__ *tag* *event* + + In this format the command returns a list containing all commands bound to + the *event* for the *tag*. Specifying an unknown tag or unknown event, will + cause the command to throw an error. + + - __::uevent::watch::tag::add__ *pattern* *command* + + This command sets up a sort of reverse events. Events generated, i.e. the + *command* prefix invoked, when observers bind to and unbind from specific + tags. + + Note that the command prefix is only invoked twice per tag, first when the + first command is bound to any event of the tag, and second when the last + command bound to the tag is removed. + + The signature of the *command* prefix is + + * __{*}command__ __bound__ *tag* + + * __{*}command__ __unbound__ *tag* + + The result of the command is a token representing the watcher. + + - __::uevent::watch::tag::remove__ *token* + + This command removes a watcher for (un)bind events on tags. + + The result of the command is the empty string. + + - __::uevent::watch::event::add__ *tag_pattern* *event_pattern* *command* + + This command sets up a sort of reverse events. Events generated, i.e. the + *command* prefix invoked, when observers bind to and unbind from specific + combinations of tags and events. + + Note that the command prefix is only invoked twice per tag/event + combination, first when the first command is bound to it, and second when + the last command bound to the it is removed. + + The signature of the *command* prefix is + + * __{*}command__ __bound__ *tag* *event* + + * __{*}command__ __unbound__ *tag* *event* + + The result of the command is a token representing the watcher. + + - __::uevent::watch::event::remove__ *token* + + This command removes a watcher for (un)bind events on tag/event + combinations. + + The result of the command is the empty string. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *uevent* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[hook(n)](../hook/hook.md) + +# KEYWORDS + +[bind](../../../../index.md#bind), [event](../../../../index.md#event), +[generate event](../../../../index.md#generate_event), +[hook](../../../../index.md#hook), [unbind](../../../../index.md#unbind) + +# CATEGORY + +Programming tools + +# COPYRIGHT + +Copyright © 2007-2012 Andreas Kupries ADDED embedded/md/tcllib/files/modules/uev/uevent_onidle.md Index: embedded/md/tcllib/files/modules/uev/uevent_onidle.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/uev/uevent_onidle.md @@ -0,0 +1,95 @@ + +[//000000001]: # (uevent::onidle - User events) +[//000000002]: # (Generated from file 'uevent_onidle.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (uevent::onidle(n) 0.1 tcllib "User events") + +# NAME + +uevent::onidle - Request merging and deferal to idle time + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Examples](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require uevent::onidle ?0.1? +package require logger + +[__::uevent::onidle__ *objectName* *commandprefix*](#1) +[*objectName* __request__](#2) + +# DESCRIPTION + +This package provides objects which can merge multiple requestes for an action +and execute the action the moment the system (event loop) becomes idle. The +action to be run is configured during object construction. + +# API + +The package exports a class, __uevent::onidle__, as specified below. + + - __::uevent::onidle__ *objectName* *commandprefix* + + The command creates a new *onidle* object with an associated global Tcl + command whose name is *objectName*. This command may be used to invoke + various operations on the object. + + The *commandprefix* is the action to perform when the event loop is idle and + the user asked for it using the method __request__ (See below). + +The object commands created by the class commands above have the form: + + - *objectName* __request__ + + This method requests the execution of the command prefix specified during + the construction of *objectName* the next time the event loop is idle. + Multiple requests are merged and cause only one execution of the command + prefix. + +# Examples + +Examples of this type of deferal are buried in the (C-level) implementations all +the Tk widgets, defering geometry calculations and window redraw activity in +this manner. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *uevent* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[callback](../../../../index.md#callback), +[deferal](../../../../index.md#deferal), [event](../../../../index.md#event), +[idle](../../../../index.md#idle), [merge](../../../../index.md#merge), +[on-idle](../../../../index.md#on_idle) + +# COPYRIGHT + +Copyright © 2008 Andreas Kupries ADDED embedded/md/tcllib/files/modules/units/units.md Index: embedded/md/tcllib/files/modules/units/units.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/units/units.md @@ -0,0 +1,383 @@ + +[//000000001]: # (units - Convert and manipulate quantities with units) +[//000000002]: # (Generated from file 'units.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (units(n) 1.2 tcllib "Convert and manipulate quantities with units") + +# NAME + +units - unit conversion + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [UNIT STRING FORMAT](#section3) + + - [Example Valid Unit Strings](#subsection1) + + - [SI UNITS](#section4) + + - [SI Base Units](#subsection2) + + - [SI Derived Units with Special Names](#subsection3) + + - [SI Prefixes](#subsection4) + + - [Non-SI Units](#subsection5) + + - [Quantities and Derived Units with Special Names](#subsection6) + + - [REFERENCES](#section5) + + - [AUTHORS](#section6) + + - [Bugs, Ideas, Feedback](#section7) + + - [Keywords](#keywords) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.1 +package require units ?2.1? + +[__::units::convert__ *value* *targetUnits*](#1) +[__::units::reduce__ *unitString*](#2) +[__::units::new__ *name* *baseUnits*](#3) + +# DESCRIPTION + +This library provides a conversion facility from a variety of scientific and +engineering shorthand notations into floating point numbers. This allows +application developers to easily convert values with different units into +uniformly scaled numbers. + +The units conversion facility is also able to convert between compatible units. +If, for example, a application is expecting a value in *ohms* (Resistance), and +the user specifies units of *milliwebers/femtocoulomb*, the conversion routine +will handle it appropriately. An error will be generated if an incorrect +conversion is attempted. + +Values are scaled from one set of units to another by dimensional analysis. Both +the value units and the target units are reduced into primitive units and a +scale factor. Units are checked for compatibility, and the scale factors are +applied by multiplication and division. This technique is extremely flexible and +quite robust. + +New units and new unit abbreviations can be defined in terms of existing units +and abbreviations. It is also possible to define a new primitive unit, although +that will probably be unnecessary. New units will most commonly be defined to +accommodate non-SI measurement systems, such as defining the unit *inch* as +*2.54 cm*. + +# COMMANDS + + - __::units::convert__ *value* *targetUnits* + + Converts the *value* string into a floating point number, scaled to the + specified *targetUnits*. The *value* string may contain a number and units. + If units are specified, then they must be compatible with the *targetUnits*. + If units are not specified for the *value*, then it will be scaled to the + target units. For example, + + % ::units::convert "2.3 miles" km + 3.7014912 + % ::units::convert 300m/s miles/hour + 671.080887616 + % ::units::convert "1.0 m kg/s^2" newton + 1.0 + % ::units::convert 1.0 millimeter + 1000.0 + + - __::units::reduce__ *unitString* + + Returns a unit string consisting of a scale factor followed by a space + separated list of sorted and reduced primitive units. The reduced unit + string may include a forward-slash (separated from the surrounding primitive + subunits by spaces) indicating that the remaining subunits are in the + denominator. Generates an error if the *unitString* is invalid. + + % ::units::reduce pascal + 1000.0 gram / meter second second + + - __::units::new__ *name* *baseUnits* + + Creates a new unit conversion with the specified name. The new unit *name* + must be only alphabetic (upper or lower case) letters. The *baseUnits* + string can consist of any valid units conversion string, including constant + factors, numerator and denominator parts, units with prefixes, and + exponents. The baseUnits may contain any number of subunits, but it must + reduce to primitive units. BaseUnits could also be the string *-primitive* + to represent a new kind of quantity which cannot be derived from other + units. But you probably would not do that unless you have discovered some + kind of new universal property. + + % ::units::new furlong "220 yards" + % ::units::new fortnight "14 days" + % ::units::convert 100m/s furlongs/fortnight + 601288.475303 + +# UNIT STRING FORMAT + +Value and unit string format is quite flexible. It is possible to define +virtually any combination of units, prefixes, and powers. Valid unit strings +must conform to these rules. + + - A unit string consists of an optional scale factor followed by zero or more + subunits. The scale factor must be a valid floating point number, and may or + may not be separated from the subunits. The scale factor could be negative. + + - Subunits are separated form each other by one or more separator characters, + which are space (" "), hyphen ("-"), asterisk ("*"), and forward-slash + ("/"). Sure, go ahead and complain about using a minus sign ("-") to + represent multiplication. It just isn't sound mathematics, and, by rights, + we should require everyone to use the asterisk ("*") to separate all units. + But the bottom line is that complex unit strings like *m-kg/s^2* are + pleasantly readable. + + - The forward-slash seperator ("/") indicates that following subunits are in + the denominator. There can be at most one forward-slash separator. + + - Subunits can be floating point scale factors, but with the exception of the + leading scale factor, they must be surrounded by valid separators. Subunit + scale factors cannot be negative. (Remember that the hyphen is a unit + separator.) + + - Subunits can be valid units or abbreviations. They may include a prefix. + They may include a plural suffix "s" or "es". They may also include a power + string denoted by a circumflex ("^"), followed by a integer, after the unit + name (or plural suffix, if there is one). Negative exponents are not + allowed. (Remember that the hyphen is a unit separator.) + +## Example Valid Unit Strings + + Unit String Reduced Unit String + ------------------------------------------------------------ + meter 1.0 meter + kilometer 1000.0 meter + km 1000.0 meter + km/s 1000.0 meter / second + /microsecond 1000000.0 / second + /us 1000000.0 / second + kg-m/s^2 1000.0 gram meter / second second + 30second 30.0 second + 30 second 30.0 second + 30 seconds 30.0 second + 200*meter/20.5*second 9.75609756098 meter / second + +# SI UNITS + +The standard SI units are predefined according to *NIST Special Publication +330*. Standard units for both SI Base Units (Table 1) and SI Derived Units with +Special Names (Tables 3a and 3b) are included here for reference. Each standard +unit name and abbreviation are included in this package. + +## SI Base Units + + Quantity Unit Name Abbr. + --------------------------------------------- + Length meter m + Mass kilogram kg + Time second s + Current ampere A + Temperature kelvin K + Amount mole mol + Luminous Intensity candela cd + +## SI Derived Units with Special Names + + Quantity Unit Name Abbr. Units Base Units + -------------------------------------------------------------------- + plane angle radian rad m/m m/m + solid angle steradian sr m^2/m^2 m^2/m^2 + frequency hertz Hz /s + force newton N m-kg/s^2 + pressure pascal Pa N/m^2 kg/m-s^2 + energy, work joule J N-m m^2-kg/s^2 + power, radiant flux watt W J/s m^2-kg/s^3 + electric charge coulomb C s-A + electric potential volt V W/A m^2-kg/s^3-A + capacitance farad F C/V s^4-A^2/m^2-kg + electric resistance ohm V/A m^2-kg/s^3-A^2 + electric conductance siemens S A/V s^3-A^2/m^2-kg + magnetic flux weber Wb V-s m^2-kg/s^2-A + magnetic flux density tesla T Wb/m^2 kg/s^2-A + inductance henry H Wb/A m^2-kg/s^2-A^2 + luminous flux lumen lm cd-sr + illuminance lux lx lm/m^2 cd-sr/m^2 + activity (of a + radionuclide) becquerel Bq /s + absorbed dose gray Gy J/kg m^2/s^2 + dose equivalent sievert Sv J/kg m^2/s^2 + +Note that the SI unit kilograms is actually implemented as grams because 1e-6 +kilogram = 1 milligram, not 1 microkilogram. The abbreviation for Electric +Resistance (ohms), which is the omega character, is not supported. + +Also note that there is no support for Celsius or Farenheit temperature. The +units conversion routines can only scale values with multiplication and +division, so it is not possible to convert from thermodynamic temperature +(kelvins) to absolute degrees Celsius or Farenheit. Conversion of thermodynamic +quantities, such as thermal expansion (per unit temperature), however, are easy +to add to the units library. + +SI Units can have a multiple or sub-multiple prefix. The prefix or its +abbreviation should appear before the unit, without spaces. Compound prefixes +are not allowed, and a prefix should never be used alone. These prefixes are +defined in Table 5 of *Special Publication 330*. + +## SI Prefixes + + Prefix Name Abbr. Factor + --------------------------------------- + yotta Y 1e24 + zetta Z 1e21 + exa E 1e18 + peta P 1e15 + tera T 1e12 + giga G 1e9 + mega M 1e6 + kilo k 1e3 + hecto h 1e2 + deka da 1e1 + deca 1e1 + + deci d 1e-1 + centi c 1e-2 + milli m 1e-3 + micro u 1e-6 + nano n 1e-9 + pico p 1e-12 + femto f 1e-15 + atto a 1e-18 + zepto z 1e-21 + yocto y 1e-24 + +Note that we define the same prefix with both the USA ("deka") and non-USA +("deca") spellings. Also note that we take the liberty of allowing "micro" to be +typed as a "u" instead of the Greek character mu. + +Many non-SI units are commonly used in applications. Appendix B.8 of *NIST +Special Publication 811* lists many non-SI conversion factors. It is not +possible to include all possible unit definitions in this package. In some +cases, many different conversion factors exist for a given unit, depending on +the context. (The appendix lists over 40 conversions for British thermal units!) +Application specific conversions can always be added using the __new__ command, +but some well known and often used conversions are included in this package. + +## Non-SI Units + + Unit Name Abbr. Base Units + -------------------------------------------------- + angstrom 1.0E-10 m + astronomicalUnit AU 1.495979E11 m + atmosphere 1.01325E5 Pa + bar 1.0E5 Pa + calorie 4.1868 J + curie 3.7E10 Bq + day 8.64E4 s + degree 1.745329E-2 rad + erg 1.0E-7 J + faraday 9.648531 C + fermi 1.0E-15 m + foot ft 3.048E-1 m + gauss 1.0E-4 T + gilbert 7.957747E-1 A + grain gr 6.479891E-5 kg + hectare ha 1.0E4 m^2 + hour h 3.6E3 s + inch in 2.54E-2 m + lightYear 9.46073E15 m + liter L 1.0E-3 m^3 + maxwell Mx 1.0E-8 Wb + mho 1.0 S + micron 1.0E-6 m + mil 2.54E-5 m + mile mi 1.609344E3 m + minute min 6.0E1 s + parsec pc 3.085E16 m + pica 4.233333E-3 m + pound lb 4.535924E-1 kg + revolution 6.283185 rad + revolutionPerMinute rpm 1.047198E-1 rad/s + yard yd 9.144E-1 m + year 3.1536E7 s + +## Quantities and Derived Units with Special Names + +This units conversion package is limited specifically to unit reduction, +comparison, and scaling. This package does not consider any of the quantity +names for either base or derived units. A similar implementation or an extension +in a typed or object-oriented language might introduce user defined types for +the quantities. Quantity type checking could be used, for example, to ensure +that all *length* values properly reduced to *meters*, or that all *velocity* +values properly reduced to *meters/second*. + +A C implementation of this package has been created to work in conjunction with +the Simplified Wrapper Interface Generator +([http://www.swig.org/](http://www.swig.org/)). That package (units.i) exploits +SWIG's typemap system to automatically convert script quantity strings into +floating point quantities. Function arguments are specified as quantity types +(e.g., *typedef float Length*), and target units (expected by the C application +code) are specified in an associative array. Default units are also defined for +each quantity type, and are applied to any unit-less quantity strings. + +A units system enhanced with quantity type checking might benefit from inclusion +of other derived types which are expressed in terms of special units, as +illustrated in Table 2 of *NIST Publication 330*. The quantity *area*, for +example, could be defined as units properly reducing to *meter^2*, although the +utility of defining a unit named *square meter* is arguable. + +# REFERENCES + +The unit names, abbreviations, and conversion values are derived from those +published by the United States Department of Commerce Technology Administration, +National Institute of Standards and Technology (NIST) in *NIST Special +Publication 330: The International System of Units (SI)* and *NIST Special +Publication 811: Guide for the Use of the International System of Units (SI)*. +Both of these publications are available (as of December 2000) from +[http://physics.nist.gov/cuu/Reference/contents.html](http://physics.nist.gov/cuu/Reference/contents.html) + +The ideas behind implementation of this package is based in part on code written +in 1993 by Adrian Mariano which performed dimensional analysis of unit strings +using fixed size tables of C structs. After going missing in the late 1990's, +Adrian's code has reappeared in the GNU Units program at +[http://www.gnu.org/software/units/](http://www.gnu.org/software/units/) + +# AUTHORS + +Robert W. Techentin + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *units* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[angle](../../../../index.md#angle), +[constants](../../../../index.md#constants), +[conversion](../../../../index.md#conversion), +[distance](../../../../index.md#distance), +[radians](../../../../index.md#radians), [unit](../../../../index.md#unit) + +# COPYRIGHT + +Copyright © 2000-2005 Mayo Foundation ADDED embedded/md/tcllib/files/modules/uri/uri.md Index: embedded/md/tcllib/files/modules/uri/uri.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/uri/uri.md @@ -0,0 +1,485 @@ + +[//000000001]: # (uri - Tcl Uniform Resource Identifier Management) +[//000000002]: # (Generated from file 'uri.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (uri(n) 1.2.7 tcllib "Tcl Uniform Resource Identifier Management") + +# NAME + +uri - URI utilities + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [SCHEMES](#section3) + + - [EXTENDING](#section4) + + - [QUIRK OPTIONS](#section5) + + - [BACKWARD COMPATIBILITY](#subsection1) + + - [NEW DESIGNS](#subsection2) + + - [DEFAULT VALUES](#subsection3) + + - [EXAMPLES](#section6) + + - [CREDITS](#section7) + + - [Bugs, Ideas, Feedback](#section8) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.2 +package require uri ?1.2.7? + +[__uri::setQuirkOption__ *option* ?*value*?](#1) +[__uri::split__ *url* ?*defaultscheme*?](#2) +[__uri::join__ ?*key* *value*?...](#3) +[__uri::resolve__ *base* *url*](#4) +[__uri::isrelative__ *url*](#5) +[__uri::geturl__ *url* ?*options*...?](#6) +[__uri::canonicalize__ *uri*](#7) +[__uri::register__ *schemeList* *script*](#8) + +# DESCRIPTION + +This package does two things. + +First, it provides a number of commands for manipulating URLs/URIs and fetching +data specified by them. For fetching data this package analyses the requested +URL/URI and then dispatches it to the appropriate package +(__[http](../../../../index.md#http)__, __[ftp](../ftp/ftp.md)__, ...) for +actual retrieval. Currently these commands are defined for the schemes +*[http](../../../../index.md#http)*, *[https](../../../../index.md#https)*, +*[ftp](../../../../index.md#ftp)*, *[mailto](../../../../index.md#mailto)*, +*[news](../../../../index.md#news)*, *[ldap](../../../../index.md#ldap)*, +*ldaps* and *[file](../../../../index.md#file)*. The package __uri::urn__ adds +scheme *[urn](../../../../index.md#urn)*. + +Second, it provides regular expressions for a number of __registered__ URL/URI +schemes. Registered schemes are currently *[ftp](../../../../index.md#ftp)*, +*[ldap](../../../../index.md#ldap)*, *ldaps*, +*[file](../../../../index.md#file)*, *[http](../../../../index.md#http)*, +*[https](../../../../index.md#https)*, *[gopher](../../../../index.md#gopher)*, +*[mailto](../../../../index.md#mailto)*, *[news](../../../../index.md#news)*, +*[wais](../../../../index.md#wais)* and +*[prospero](../../../../index.md#prospero)*. The package __uri::urn__ adds +scheme *[urn](../../../../index.md#urn)*. + +The commands of the package conform to RFC 3986 +([https://www.rfc-editor.org/rfc/rfc3986.txt](https://www.rfc-editor.org/rfc/rfc3986.txt)), +with the exception of a loophole arising from RFC 1630 and described in RFC 3986 +Sections 5.2.2 and 5.4.2. The loophole allows a relative URI to include a scheme +if it is the same as the scheme of the base URI against which it is resolved. +RFC 3986 recommends avoiding this usage. + +# COMMANDS + + - __uri::setQuirkOption__ *option* ?*value*? + + __uri::setQuirkOption__ is an accessor command for a number of "quirk + options". The command has the same semantics as the command + __[set](../../../../index.md#set)__: when called with one argument it reads + an existing value; with two arguments it writes a new value. The value of a + "quirk option" is boolean: the value __false__ requests conformance with RFC + 3986, while __true__ requests use of the quirk. See section [QUIRK + OPTIONS](#section5) for discussion of the different options and their + purpose. + + - __uri::split__ *url* ?*defaultscheme*? + + __uri::split__ takes a *url*, decodes it and then returns a list of + key/value pairs suitable for __array set__ containing the constituents of + the *url*. If the scheme is missing from the *url* it defaults to the value + of *defaultscheme* if it was specified, or + *[http](../../../../index.md#http)* else. Currently the schemes + *[http](../../../../index.md#http)*, *[https](../../../../index.md#https)*, + *[ftp](../../../../index.md#ftp)*, *[mailto](../../../../index.md#mailto)*, + *[news](../../../../index.md#news)*, *[ldap](../../../../index.md#ldap)*, + *ldaps* and *[file](../../../../index.md#file)* are supported by the package + itself. See section [EXTENDING](#section4) on how to expand that range. + + The set of constituents of a URL (= the set of keys in the returned + dictionary) is dependent on the scheme of the URL. The only key which is + therefore always present is __scheme__. For the following schemes the + constituents and their keys are known: + + * ftp + + __user__, __pwd__, __host__, __port__, __path__, __type__, __pbare__. + The pbare is optional. + + * http(s) + + __user__, __pwd__, __host__, __port__, __path__, __query__, + __fragment__, __pbare__. The pbare is optional. + + * file + + __path__, __host__. The host is optional. + + * mailto + + __user__, __host__. The host is optional. + + * ldap(s) + + __host__, __port__, __dn__, __attrs__, __scope__, __filter__, + __extensions__ + + * news + + Either __message-id__ or __newsgroup-name__. + + For discussion of the boolean __pbare__ see options *NoInitialSlash* and + *NoExtraKeys* in [QUIRK OPTIONS](#section5). + + The constituents are returned as slices of the argument *url*, without + removal of percent-encoding ("url-encoding") or other adaptations. Notably, + on Windows® the __path__ in scheme *[file](../../../../index.md#file)* is + not a valid local filename. See [EXAMPLES](#section6) for more information. + + - __uri::join__ ?*key* *value*?... + + __uri::join__ takes a list of key/value pairs (generated by __uri::split__, + for example) and returns the canonical URL they represent. Currently the + schemes *[http](../../../../index.md#http)*, + *[https](../../../../index.md#https)*, *[ftp](../../../../index.md#ftp)*, + *[mailto](../../../../index.md#mailto)*, + *[news](../../../../index.md#news)*, *[ldap](../../../../index.md#ldap)*, + *ldaps* and *[file](../../../../index.md#file)* are supported by the package + itself. See section [EXTENDING](#section4) on how to expand that range. + + The arguments are expected to be slices of a valid URL, with + percent-encoding ("url-encoding") and any other necessary adaptations. + Notably, on Windows the __path__ in scheme + *[file](../../../../index.md#file)* is not a valid local filename. See + [EXAMPLES](#section6) for more information. + + - __uri::resolve__ *base* *url* + + __uri::resolve__ resolves the specified *url* relative to *base*, in + conformance with RFC 3986. In other words: a non-relative *url* is returned + unchanged, whereas for a relative *url* the missing parts are taken from + *base* and prepended to it. The result of this operation is returned. For an + empty *url* the result is *base*, without its URI fragment (if any). The + command is available for schemes *[http](../../../../index.md#http)*, + *[https](../../../../index.md#https)*, *[ftp](../../../../index.md#ftp)*, + and *[file](../../../../index.md#file)*. + + - __uri::isrelative__ *url* + + __uri::isrelative__ determines whether the specified *url* is absolute or + relative. The command is available for a *url* of any scheme. + + - __uri::geturl__ *url* ?*options*...? + + __uri::geturl__ decodes the specified *url* and then dispatches the request + to the package appropriate for the scheme found in the URL. The command + assumes that the package to handle the given scheme either has the same name + as the scheme itself (including possible capitalization) followed by + __::geturl__, or, in case of this failing, has the same name as the scheme + itself (including possible capitalization). It further assumes that whatever + package was loaded provides a __geturl__-command in the namespace of the + same name as the package itself. This command is called with the given *url* + and all given *options*. Currently __geturl__ does not handle any options + itself. + + *Note:* *[file](../../../../index.md#file)*-URLs are an exception to the + rule described above. They are handled internally. + + It is not possible to specify results of the command. They depend on the + __geturl__-command for the scheme the request was dispatched to. + + - __uri::canonicalize__ *uri* + + __uri::canonicalize__ returns the canonical form of a URI. The canonical + form of a URI is one where relative path specifications, i.e. "." and "..", + have been resolved. The command is available for all URI schemes that have + __uri::split__ and __uri::join__ commands. The command returns a + canonicalized URI if the URI scheme has a __path__ component (i.e. + *[http](../../../../index.md#http)*, *[https](../../../../index.md#https)*, + *[ftp](../../../../index.md#ftp)*, and *[file](../../../../index.md#file)*). + For schemes that have __uri::split__ and __uri::join__ commands but no + __path__ component (i.e. *[mailto](../../../../index.md#mailto)*, + *[news](../../../../index.md#news)*, *[ldap](../../../../index.md#ldap)*, + and *ldaps*), the command returns the *uri* unchanged. + + - __uri::register__ *schemeList* *script* + + __uri::register__ registers the first element of *schemeList* as a new + scheme and the remaining elements as aliases for this scheme. It creates the + namespace for the scheme and executes the *script* in the new namespace. The + script has to declare variables containing regular expressions relevant to + the scheme. At least the variable __schemepart__ has to be declared as that + one is used to extend the variables keeping track of the registered schemes. + +# SCHEMES + +In addition to the commands mentioned above this package provides regular +expression to recognize URLs for a number of URL schemes. + +For each supported scheme a namespace of the same name as the scheme itself is +provided inside of the namespace *uri* containing the variable __url__ whose +contents are a regular expression to recognize URLs of that scheme. Additional +variables may contain regular expressions for parts of URLs for that scheme. + +The variable __uri::schemes__ contains a list of all registered schemes. +Currently these are *[ftp](../../../../index.md#ftp)*, +*[ldap](../../../../index.md#ldap)*, *ldaps*, +*[file](../../../../index.md#file)*, *[http](../../../../index.md#http)*, +*[https](../../../../index.md#https)*, *[gopher](../../../../index.md#gopher)*, +*[mailto](../../../../index.md#mailto)*, *[news](../../../../index.md#news)*, +*[wais](../../../../index.md#wais)* and +*[prospero](../../../../index.md#prospero)*. + +# EXTENDING + +Extending the range of schemes supported by __uri::split__ and __uri::join__ is +easy because both commands do not handle the request by themselves but dispatch +it to another command in the *uri* namespace using the scheme of the URL as +criterion. + +__uri::split__ and __uri::join__ call __Split[string totitle ]__ and +__Join[string totitle ]__ respectively. + +The provision of split and join commands is sufficient to extend the commands +__uri::canonicalize__ and __uri::geturl__ (the latter subject to the +availability of a suitable package with a __geturl__ command). In contrast, to +extend the command __uri::resolve__ to a new scheme, the command itself must be +modified. + +To extend the range of schemes for which pattern information is available, use +the command __uri::register__. + +An example of a package that provides both commands and pattern information for +a new scheme is __uri::urn__, which adds scheme +*[urn](../../../../index.md#urn)*. + +# QUIRK OPTIONS + +The value of a "quirk option" is boolean: the value __false__ requests +conformance with RFC 3986, while __true__ requests use of the quirk. Use command +__uri::setQuirkOption__ to access the values of quirk options. + +Quirk options are useful both for allowing backwards compatibility when a +command specification changes, and for adding useful features that are not +included in RFC specifications. The following quirk options are currently +defined: + + - *NoInitialSlash* + + This quirk option concerns the leading character of __path__ (if non-empty) + in the schemes *[http](../../../../index.md#http)*, + *[https](../../../../index.md#https)*, and + *[ftp](../../../../index.md#ftp)*. + + RFC 3986 defines __path__ in an absolute URI to have an initial "/", unless + the value of __path__ is the empty string. For the scheme + *[file](../../../../index.md#file)*, all versions of package __uri__ follow + this rule. The quirk option *NoInitialSlash* does not apply to scheme + *[file](../../../../index.md#file)*. + + For the schemes *[http](../../../../index.md#http)*, + *[https](../../../../index.md#https)*, and + *[ftp](../../../../index.md#ftp)*, versions of __uri__ before 1.2.7 define + the __path__ *NOT* to include an initial "/". When the quirk option + *NoInitialSlash* is __true__ (the default), this behavior is also used in + version 1.2.7. To use instead values of __path__ as defined by RFC 3986, set + this quirk option to __false__. + + This setting does not affect RFC 3986 conformance. If *NoInitialSlash* is + __true__, then the value of __path__ in the schemes + *[http](../../../../index.md#http)*, *[https](../../../../index.md#https)*, + or *[ftp](../../../../index.md#ftp)*, cannot distinguish between URIs in + which the full "RFC 3986 path" is the empty string "" or a single slash "/" + respectively. The missing information is recorded in an additional + __uri::split__ key __pbare__. + + The boolean __pbare__ is defined when quirk options *NoInitialSlash* and + *NoExtraKeys* have values __true__ and __false__ respectively. In this case, + if the value of __path__ is the empty string "", __pbare__ is __true__ if + the full "RFC 3986 path" is "", and __pbare__ is __false__ if the full "RFC + 3986 path" is "/". + + Using this quirk option *NoInitialSlash* is a matter of preference. + + - *NoExtraKeys* + + This quirk option permits full backward compatibility with versions of + __uri__ before 1.2.7, by omitting the __uri::split__ key __pbare__ described + above (see quirk option *NoInitialSlash*). The outcome is greater backward + compatibility of the __uri::split__ command, but an inability to distinguish + between URIs in which the full "RFC 3986 path" is the empty string "" or a + single slash "/" respectively - i.e. a minor non-conformance with RFC 3986. + + If the quirk option *NoExtraKeys* is __false__ (the default), command + __uri::split__ returns an additional key __pbare__, and the commands comply + with RFC 3986. If the quirk option *NoExtraKeys* is __true__, the key + __pbare__ is not defined and there is not full conformance with RFC 3986. + + Using the quirk option *NoExtraKeys* is *NOT* recommended, because if set to + __true__ it will reduce conformance with RFC 3986. The option is included + only for compatibility with code, written for earlier versions of __uri__, + that needs values of __path__ without a leading "/", *AND ALSO* cannot + tolerate unexpected keys in the results of __uri::split__. + + - *HostAsDriveLetter* + + When handling the scheme *[file](../../../../index.md#file)* on the Windows + platform, versions of __uri__ before 1.2.7 use the __host__ field to + represent a Windows drive letter and the colon that follows it, and the + __path__ field to represent the filename path after the colon. Such URIs are + invalid, and are not recognized by any RFC. When the quirk option + *HostAsDriveLetter* is __true__, this behavior is also used in version + 1.2.7. To use *[file](../../../../index.md#file)* URIs on Windows that + conform to RFC 3986, set this quirk option to __false__ (the default). + + Using this quirk is *NOT* recommended, because if set to __true__ it will + cause the __uri__ commands to expect and produce invalid URIs. The option is + included only for compatibility with legacy code. + + - *RemoveDoubleSlashes* + + When a URI is canonicalized by __uri::canonicalize__, its __path__ is + normalized by removal of segments "." and "..". RFC 3986 does not mandate + the removal of empty segments "" (i.e. the merger of double slashes, which + is a feature of filename normalization but not of URI __path__ + normalization): it treats URIs with excess slashes as referring to different + resources. When the quirk option *RemoveDoubleSlashes* is __true__ (the + default), empty segments will be removed from __path__. To prevent removal, + and thereby conform to RFC 3986, set this quirk option to __false__. + + Using this quirk is a matter of preference. A URI with double slashes in its + path was most likely generated by error, certainly so if it has a + straightforward mapping to a file on a server. In some cases it may be + better to sanitize the URI; in others, to keep the URI and let the server + handle the possible error. + +## BACKWARD COMPATIBILITY + +To behave as similarly as possible to versions of __uri__ earlier than 1.2.7, +set the following quirk options: + + - __uri::setQuirkOption__ *NoInitialSlash* 1 + + - __uri::setQuirkOption__ *NoExtraKeys* 1 + + - __uri::setQuirkOption__ *HostAsDriveLetter* 1 + + - __uri::setQuirkOption__ *RemoveDoubleSlashes* 0 + +In code that can tolerate the return by __uri::split__ of an additional key +__pbare__, set + + - __uri::setQuirkOption__ *NoExtraKeys* 0 + +in order to achieve greater compliance with RFC 3986. + +## NEW DESIGNS + +For new projects, the following settings are recommended: + + - __uri::setQuirkOption__ *NoInitialSlash* 0 + + - __uri::setQuirkOption__ *NoExtraKeys* 0 + + - __uri::setQuirkOption__ *HostAsDriveLetter* 0 + + - __uri::setQuirkOption__ *RemoveDoubleSlashes* 0|1 + +## DEFAULT VALUES + +The default values for package __uri__ version 1.2.7 are intended to be a +compromise between backwards compatibility and improved features. Different +default values may be chosen in future versions of package __uri__. + + - __uri::setQuirkOption__ *NoInitialSlash* 1 + + - __uri::setQuirkOption__ *NoExtraKeys* 0 + + - __uri::setQuirkOption__ *HostAsDriveLetter* 0 + + - __uri::setQuirkOption__ *RemoveDoubleSlashes* 1 + +# EXAMPLES + +A Windows® local filename such as "__C:\Other Files\startup.txt__" is not +suitable for use as the __path__ element of a URI in the scheme +*[file](../../../../index.md#file)*. + +The Tcl command __file normalize__ will convert the backslashes to forward +slashes. To generate a valid __path__ for the scheme +*[file](../../../../index.md#file)*, the normalized filename must be prepended +with "__/__", and then any characters that do not match the __regexp__ bracket +expression + + [a-zA-Z0-9$_.+!*'(,)?:@&=-] + +must be percent-encoded. + +The result in this example is "__/C:/Other%20Files/startup.txt__" which is a +valid value for __path__. + + % uri::join path /C:/Other%20Files/startup.txt scheme file + + file:///C:/Other%20Files/startup.txt + + % uri::split file:///C:/Other%20Files/startup.txt + + path /C:/Other%20Files/startup.txt scheme file + +On UNIX® systems filenames begin with "__/__" which is also used as the +directory separator. The only action needed to convert a filename to a valid +__path__ is percent-encoding. + +# CREDITS + +Original code (regular expressions) by Andreas Kupries. Modularisation by Steve +Ball, also the split/join/resolve functionality. RFC 3986 conformance by Keith +Nash. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *uri* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[fetching information](../../../../index.md#fetching_information), +[file](../../../../index.md#file), [ftp](../../../../index.md#ftp), +[gopher](../../../../index.md#gopher), [http](../../../../index.md#http), +[https](../../../../index.md#https), [ldap](../../../../index.md#ldap), +[mailto](../../../../index.md#mailto), [news](../../../../index.md#news), +[prospero](../../../../index.md#prospero), [rfc +1630](../../../../index.md#rfc_1630), [rfc 2255](../../../../index.md#rfc_2255), +[rfc 2396](../../../../index.md#rfc_2396), [rfc +3986](../../../../index.md#rfc_3986), [uri](../../../../index.md#uri), +[url](../../../../index.md#url), [wais](../../../../index.md#wais), +[www](../../../../index.md#www) + +# CATEGORY + +Networking ADDED embedded/md/tcllib/files/modules/uri/urn-scheme.md Index: embedded/md/tcllib/files/modules/uri/urn-scheme.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/uri/urn-scheme.md @@ -0,0 +1,79 @@ + +[//000000001]: # (uri_urn - Tcl Uniform Resource Identifier Management) +[//000000002]: # (Generated from file 'urn-scheme.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (uri_urn(n) 1.0.3 tcllib "Tcl Uniform Resource Identifier Management") + +# NAME + +uri_urn - URI utilities, URN scheme + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.2 +package require uri::urn ?1.0.3? + +[__uri::urn::quote__ *url*](#1) +[__uri::urn::unquote__ *url*](#2) + +# DESCRIPTION + +This package provides two commands to quote and unquote the disallowed +characters for url using the *[urn](../../../../index.md#urn)* scheme, registers +the scheme with the package __[uri](uri.md)__, and provides internal helpers +which will be automatically used by the commands __uri::split__ and +__uri::join__ of package __[uri](uri.md)__ to handle urls using the +*[urn](../../../../index.md#urn)* scheme. + +# COMMANDS + + - __uri::urn::quote__ *url* + + This command quotes the characters disallowed by the + *[urn](../../../../index.md#urn)* scheme (per RFC 2141 sec2.2) in the *url* + and returns the modified url as its result. + + - __uri::urn::unquote__ *url* + + This commands performs the reverse of __::uri::urn::quote__. It takes an + *[urn](../../../../index.md#urn)* url, removes the quoting from all + disallowed characters, and returns the modified urls as its result. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *uri* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[rfc 2141](../../../../index.md#rfc_2141), [uri](../../../../index.md#uri), +[url](../../../../index.md#url), [urn](../../../../index.md#urn) + +# CATEGORY + +Networking ADDED embedded/md/tcllib/files/modules/uuid/uuid.md Index: embedded/md/tcllib/files/modules/uuid/uuid.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/uuid/uuid.md @@ -0,0 +1,94 @@ + +[//000000001]: # (uuid - uuid) +[//000000002]: # (Generated from file 'uuid.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (uuid(n) 1.0.6 tcllib "uuid") + +# NAME + +uuid - UUID generation and comparison + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [EXAMPLES](#section3) + + - [REFERENCES](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require uuid ?1.0.6? + +[__::uuid::uuid generate__](#1) +[__::uuid::uuid equal__ *id1* *id2*](#2) + +# DESCRIPTION + +This package provides a generator of universally unique identifiers (UUID) also +known as globally unique identifiers (GUID). This implementation follows the +draft specification from (1) although this is actually an expired draft +document. + +# COMMANDS + + - __::uuid::uuid generate__ + + Creates a type 4 uuid by MD5 hashing a number of bits of variant data + including the time and hostname. Returns the string representation of the + new uuid. + + - __::uuid::uuid equal__ *id1* *id2* + + Compares two uuids and returns true if both arguments are the same uuid. + +# EXAMPLES + + % uuid::uuid generate + b12dc22c-5c36-41d2-57da-e29d0ef5839c + +# REFERENCES + + 1. Paul J. Leach, "UUIDs and GUIDs", February 1998. + ([http://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt](http://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt)) + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *uuid* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[GUID](../../../../index.md#guid), [UUID](../../../../index.md#uuid) + +# CATEGORY + +Hashes, checksums, and encryption + +# COPYRIGHT + +Copyright © 2004, Pat Thoyts ADDED embedded/md/tcllib/files/modules/valtype/cc_amex.md Index: embedded/md/tcllib/files/modules/valtype/cc_amex.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/cc_amex.md @@ -0,0 +1,146 @@ + +[//000000001]: # (valtype::creditcard::amex - Validation types) +[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::creditcard::amex(n) 1 tcllib "Validation types") + +# NAME + +valtype::creditcard::amex - Validation for AMEX creditcard number + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit 2 +package require valtype::common +package require valtype::luhn +package require valtype::creditcard::amex ?1? + +[__valtype::creditcard::amex__ __validate__ *value*](#1) +[__valtype::creditcard::amex__ __checkdigit__ *value*](#2) + +# DESCRIPTION + +This package implements a snit validation type for an AMEX creditcard number. + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__, a validation type defined by +the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is +an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + valtype::creditcard::amex validate .... ;# Does nothing + valtype::creditcard::amex validate .... ;# Throws an error (bad American Expresss creditcard number). + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error, possibly with additional elements +which provide more details about the problem. + +# API + +The API provided by this package satisfies the specification of snit validation +types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*. + + - __valtype::creditcard::amex__ __validate__ *value* + + This method validates the *value* and returns it, possibly in a canonical + form, if it passes. If the value does not pass the validation an error is + thrown. + + - __valtype::creditcard::amex__ __checkdigit__ *value* + + This method computes a check digit for the *value*. Before doing so it is + validated, except for a checkdigit. If the value does not pass the + validation no check digit is calculated and an error is thrown instead. + +# Error Codes + +As said in the package description, the errors thrown by the commands of this +package in response to input validation failures use the __-errorcode__ INVALID +to distinguish themselves from package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. Here this is __CREDITCARD AMEX__. This is then +followed by values detailing the reason for the failure. The full set of +__-errorCode__s which can be thrown by this package are: + + - INVALID CREDITCARD AMEX CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be an AMEX creditcard number. + + - INVALID CREDITCARD AMEX CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + + - INVALID CREDITCARD AMEX LENGTH + + The input value is of the wrong length to be an AMEX creditcard number. + + - INVALID CREDITCARD AMEX PREFIX + + The input value does not start with the magic value(s) required for it to be + an AMEX creditcard number. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[AMEX](../../../../index.md#amex), [American +Express](../../../../index.md#american_express), +[Checking](../../../../index.md#checking), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), +[bank](../../../../index.md#bank), [card for +credit](../../../../index.md#card_for_credit), [credit +card](../../../../index.md#credit_card), +[finance](../../../../index.md#finance), [isA](../../../../index.md#isa) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/valtype/cc_discover.md Index: embedded/md/tcllib/files/modules/valtype/cc_discover.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/cc_discover.md @@ -0,0 +1,145 @@ + +[//000000001]: # (valtype::creditcard::discover - Validation types) +[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::creditcard::discover(n) 1 tcllib "Validation types") + +# NAME + +valtype::creditcard::discover - Validation for Discover creditcard number + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit 2 +package require valtype::common +package require valtype::luhn +package require valtype::creditcard::discover ?1? + +[__valtype::creditcard::discover__ __validate__ *value*](#1) +[__valtype::creditcard::discover__ __checkdigit__ *value*](#2) + +# DESCRIPTION + +This package implements a snit validation type for a Discover creditcard number. + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__, a validation type defined by +the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is +an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + valtype::creditcard::discover validate .... ;# Does nothing + valtype::creditcard::discover validate .... ;# Throws an error (bad Discover creditcard number). + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error, possibly with additional elements +which provide more details about the problem. + +# API + +The API provided by this package satisfies the specification of snit validation +types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*. + + - __valtype::creditcard::discover__ __validate__ *value* + + This method validates the *value* and returns it, possibly in a canonical + form, if it passes. If the value does not pass the validation an error is + thrown. + + - __valtype::creditcard::discover__ __checkdigit__ *value* + + This method computes a check digit for the *value*. Before doing so it is + validated, except for a checkdigit. If the value does not pass the + validation no check digit is calculated and an error is thrown instead. + +# Error Codes + +As said in the package description, the errors thrown by the commands of this +package in response to input validation failures use the __-errorcode__ INVALID +to distinguish themselves from package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. Here this is __CREDITCARD DISCOVER__. This is then +followed by values detailing the reason for the failure. The full set of +__-errorCode__s which can be thrown by this package are: + + - INVALID CREDITCARD DISCOVER CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be a Discover creditcard number. + + - INVALID CREDITCARD DISCOVER CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + + - INVALID CREDITCARD DISCOVER LENGTH + + The input value is of the wrong length to be a Discover creditcard number. + + - INVALID CREDITCARD DISCOVER PREFIX + + The input value does not start with the magic value(s) required for it to be + a Discover creditcard number. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Checking](../../../../index.md#checking), +[Discover](../../../../index.md#discover), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), +[bank](../../../../index.md#bank), [card for +credit](../../../../index.md#card_for_credit), [credit +card](../../../../index.md#credit_card), +[finance](../../../../index.md#finance), [isA](../../../../index.md#isa) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/valtype/cc_mastercard.md Index: embedded/md/tcllib/files/modules/valtype/cc_mastercard.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/cc_mastercard.md @@ -0,0 +1,146 @@ + +[//000000001]: # (valtype::creditcard::mastercard - Validation types) +[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::creditcard::mastercard(n) 1 tcllib "Validation types") + +# NAME + +valtype::creditcard::mastercard - Validation for Mastercard creditcard number + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit 2 +package require valtype::common +package require valtype::luhn +package require valtype::creditcard::mastercard ?1? + +[__valtype::creditcard::mastercard__ __validate__ *value*](#1) +[__valtype::creditcard::mastercard__ __checkdigit__ *value*](#2) + +# DESCRIPTION + +This package implements a snit validation type for a Mastercard creditcard +number. + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__, a validation type defined by +the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is +an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + valtype::creditcard::mastercard validate .... ;# Does nothing + valtype::creditcard::mastercard validate .... ;# Throws an error (bad Mastercard creditcard number). + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error, possibly with additional elements +which provide more details about the problem. + +# API + +The API provided by this package satisfies the specification of snit validation +types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*. + + - __valtype::creditcard::mastercard__ __validate__ *value* + + This method validates the *value* and returns it, possibly in a canonical + form, if it passes. If the value does not pass the validation an error is + thrown. + + - __valtype::creditcard::mastercard__ __checkdigit__ *value* + + This method computes a check digit for the *value*. Before doing so it is + validated, except for a checkdigit. If the value does not pass the + validation no check digit is calculated and an error is thrown instead. + +# Error Codes + +As said in the package description, the errors thrown by the commands of this +package in response to input validation failures use the __-errorcode__ INVALID +to distinguish themselves from package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. Here this is __CREDITCARD MASTERCARD__. This is then +followed by values detailing the reason for the failure. The full set of +__-errorCode__s which can be thrown by this package are: + + - INVALID CREDITCARD MASTERCARD CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be a Mastercard creditcard number. + + - INVALID CREDITCARD MASTERCARD CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + + - INVALID CREDITCARD MASTERCARD LENGTH + + The input value is of the wrong length to be a Mastercard creditcard number. + + - INVALID CREDITCARD MASTERCARD PREFIX + + The input value does not start with the magic value(s) required for it to be + a Mastercard creditcard number. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Checking](../../../../index.md#checking), +[MasterCard](../../../../index.md#mastercard), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), +[bank](../../../../index.md#bank), [card for +credit](../../../../index.md#card_for_credit), [credit +card](../../../../index.md#credit_card), +[finance](../../../../index.md#finance), [isA](../../../../index.md#isa) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/valtype/cc_visa.md Index: embedded/md/tcllib/files/modules/valtype/cc_visa.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/cc_visa.md @@ -0,0 +1,145 @@ + +[//000000001]: # (valtype::creditcard::visa - Validation types) +[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::creditcard::visa(n) 1 tcllib "Validation types") + +# NAME + +valtype::creditcard::visa - Validation for VISA creditcard number + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit 2 +package require valtype::common +package require valtype::luhn +package require valtype::creditcard::visa ?1? + +[__valtype::creditcard::visa__ __validate__ *value*](#1) +[__valtype::creditcard::visa__ __checkdigit__ *value*](#2) + +# DESCRIPTION + +This package implements a snit validation type for a VISA creditcard number. + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__, a validation type defined by +the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is +an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + valtype::creditcard::visa validate .... ;# Does nothing + valtype::creditcard::visa validate .... ;# Throws an error (bad VISA creditcard number). + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error, possibly with additional elements +which provide more details about the problem. + +# API + +The API provided by this package satisfies the specification of snit validation +types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*. + + - __valtype::creditcard::visa__ __validate__ *value* + + This method validates the *value* and returns it, possibly in a canonical + form, if it passes. If the value does not pass the validation an error is + thrown. + + - __valtype::creditcard::visa__ __checkdigit__ *value* + + This method computes a check digit for the *value*. Before doing so it is + validated, except for a checkdigit. If the value does not pass the + validation no check digit is calculated and an error is thrown instead. + +# Error Codes + +As said in the package description, the errors thrown by the commands of this +package in response to input validation failures use the __-errorcode__ INVALID +to distinguish themselves from package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. Here this is __CREDITCARD VISA__. This is then +followed by values detailing the reason for the failure. The full set of +__-errorCode__s which can be thrown by this package are: + + - INVALID CREDITCARD VISA CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be a VISA creditcard number. + + - INVALID CREDITCARD VISA CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + + - INVALID CREDITCARD VISA LENGTH + + The input value is of the wrong length to be a VISA creditcard number. + + - INVALID CREDITCARD VISA PREFIX + + The input value does not start with the magic value(s) required for it to be + a VISA creditcard number. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Checking](../../../../index.md#checking), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[VISA](../../../../index.md#visa), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), +[bank](../../../../index.md#bank), [card for +credit](../../../../index.md#card_for_credit), [credit +card](../../../../index.md#credit_card), +[finance](../../../../index.md#finance), [isA](../../../../index.md#isa) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/valtype/ean13.md Index: embedded/md/tcllib/files/modules/valtype/ean13.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/ean13.md @@ -0,0 +1,137 @@ + +[//000000001]: # (valtype::gs1::ean13 - Validation types) +[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::gs1::ean13(n) 1 tcllib "Validation types") + +# NAME + +valtype::gs1::ean13 - Validation for EAN13 + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit 2 +package require valtype::common +package require valtype::gs1::ean13 ?1? + +[__valtype::gs1::ean13__ __validate__ *value*](#1) +[__valtype::gs1::ean13__ __checkdigit__ *value*](#2) + +# DESCRIPTION + +This package implements a snit validation type for an EAN13. + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__, a validation type defined by +the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is +an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + valtype::gs1::ean13 validate .... ;# Does nothing + valtype::gs1::ean13 validate .... ;# Throws an error (bad EAN13). + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error, possibly with additional elements +which provide more details about the problem. + +# API + +The API provided by this package satisfies the specification of snit validation +types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*. + + - __valtype::gs1::ean13__ __validate__ *value* + + This method validates the *value* and returns it, possibly in a canonical + form, if it passes. If the value does not pass the validation an error is + thrown. + + - __valtype::gs1::ean13__ __checkdigit__ *value* + + This method computes a check digit for the *value*. Before doing so it is + validated, except for a checkdigit. If the value does not pass the + validation no check digit is calculated and an error is thrown instead. + +# Error Codes + +As said in the package description, the errors thrown by the commands of this +package in response to input validation failures use the __-errorcode__ INVALID +to distinguish themselves from package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. Here this is __EAN13__. This is then followed by +values detailing the reason for the failure. The full set of __-errorCode__s +which can be thrown by this package are: + + - INVALID EAN13 CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be an EAN13. + + - INVALID EAN13 CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + + - INVALID EAN13 LENGTH + + The input value is of the wrong length to be an EAN13. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Checking](../../../../index.md#checking), [EAN](../../../../index.md#ean), +[EAN13](../../../../index.md#ean13), [European Article +Number](../../../../index.md#european_article_number), [International Article +Number](../../../../index.md#international_article_number), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/valtype/iban.md Index: embedded/md/tcllib/files/modules/valtype/iban.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/iban.md @@ -0,0 +1,134 @@ + +[//000000001]: # (valtype::iban - Validation types) +[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::iban(n) 1.7 tcllib "Validation types") + +# NAME + +valtype::iban - Validation for IBAN + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit 2 +package require valtype::common +package require valtype::iban ?1.7? + +[__valtype::iban__ __validate__ *value*](#1) +[__valtype::iban__ __checkdigit__ *value*](#2) + +# DESCRIPTION + +This package implements a snit validation type for an IBAN. + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__, a validation type defined by +the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is +an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + valtype::iban validate .... ;# Does nothing + valtype::iban validate .... ;# Throws an error (bad International Bank Account Number). + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error, possibly with additional elements +which provide more details about the problem. + +# API + +The API provided by this package satisfies the specification of snit validation +types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*. + + - __valtype::iban__ __validate__ *value* + + This method validates the *value* and returns it, possibly in a canonical + form, if it passes. If the value does not pass the validation an error is + thrown. + + - __valtype::iban__ __checkdigit__ *value* + + This method computes a check digit for the *value*. Before doing so it is + validated, except for a checkdigit. If the value does not pass the + validation no check digit is calculated and an error is thrown instead. + +# Error Codes + +As said in the package description, the errors thrown by the commands of this +package in response to input validation failures use the __-errorcode__ INVALID +to distinguish themselves from package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. Here this is __IBAN__. This is then followed by +values detailing the reason for the failure. The full set of __-errorCode__s +which can be thrown by this package are: + + - INVALID IBAN CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be an IBAN. + + - INVALID IBAN CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Checking](../../../../index.md#checking), [IBAN](../../../../index.md#iban), +[International Bank Account +Number](../../../../index.md#international_bank_account_number), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), +[bank](../../../../index.md#bank), [finance](../../../../index.md#finance), +[isA](../../../../index.md#isa) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/valtype/imei.md Index: embedded/md/tcllib/files/modules/valtype/imei.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/imei.md @@ -0,0 +1,140 @@ + +[//000000001]: # (valtype::imei - Validation types) +[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::imei(n) 1 tcllib "Validation types") + +# NAME + +valtype::imei - Validation for IMEI + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit 2 +package require valtype::common +package require valtype::luhn +package require valtype::imei ?1? + +[__valtype::imei__ __validate__ *value*](#1) +[__valtype::imei__ __checkdigit__ *value*](#2) + +# DESCRIPTION + +This package implements a snit validation type for an IMEI. + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__, a validation type defined by +the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is +an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + valtype::imei validate .... ;# Does nothing + valtype::imei validate .... ;# Throws an error (bad International Mobile Equipment Identity (IMEI) number). + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error, possibly with additional elements +which provide more details about the problem. + +# API + +The API provided by this package satisfies the specification of snit validation +types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*. + + - __valtype::imei__ __validate__ *value* + + This method validates the *value* and returns it, possibly in a canonical + form, if it passes. If the value does not pass the validation an error is + thrown. + + - __valtype::imei__ __checkdigit__ *value* + + This method computes a check digit for the *value*. Before doing so it is + validated, except for a checkdigit. If the value does not pass the + validation no check digit is calculated and an error is thrown instead. + +# Error Codes + +As said in the package description, the errors thrown by the commands of this +package in response to input validation failures use the __-errorcode__ INVALID +to distinguish themselves from package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. Here this is __IMEI__. This is then followed by +values detailing the reason for the failure. The full set of __-errorCode__s +which can be thrown by this package are: + + - INVALID IMEI CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be an IMEI. + + - INVALID IMEI CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + + - INVALID IMEI LENGTH + + The input value is of the wrong length to be an IMEI. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Checking](../../../../index.md#checking), [IMEI](../../../../index.md#imei), +[International Mobile Equipment +Identity](../../../../index.md#international_mobile_equipment_identity), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), +[cell-phone](../../../../index.md#cell_phone), [isA](../../../../index.md#isa), +[mobile phone](../../../../index.md#mobile_phone), +[phone](../../../../index.md#phone) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/valtype/isbn.md Index: embedded/md/tcllib/files/modules/valtype/isbn.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/isbn.md @@ -0,0 +1,148 @@ + +[//000000001]: # (valtype::isbn - Validation types) +[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::isbn(n) 1 tcllib "Validation types") + +# NAME + +valtype::isbn - Validation for ISBN + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit 2 +package require valtype::common +package require valtype::isbn ?1? + +[__valtype::isbn__ __validate__ *value*](#1) +[__valtype::isbn__ __checkdigit__ *value*](#2) +[__valtype::isbn__ __13of__ *value*](#3) + +# DESCRIPTION + +This package implements a snit validation type for an ISBN. + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__, a validation type defined by +the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is +an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + valtype::isbn validate .... ;# Does nothing + valtype::isbn validate .... ;# Throws an error (bad ISBN). + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error, possibly with additional elements +which provide more details about the problem. + +# API + +The API provided by this package satisfies the specification of snit validation +types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*. + + - __valtype::isbn__ __validate__ *value* + + This method validates the *value* and returns it, possibly in a canonical + form, if it passes. If the value does not pass the validation an error is + thrown. + + - __valtype::isbn__ __checkdigit__ *value* + + This method computes a check digit for the *value*. Before doing so it is + validated, except for a checkdigit. If the value does not pass the + validation no check digit is calculated and an error is thrown instead. + + - __valtype::isbn__ __13of__ *value* + + This method expects an old-style 10-digit ISBN and returns the canonical + modern 13-digit ISBN. This is used by __validate__ to canonicalize the + input, so that all parts of the system after the validation can expect to + work with modern 13-digit ISBNs. + +# Error Codes + +As said in the package description, the errors thrown by the commands of this +package in response to input validation failures use the __-errorcode__ INVALID +to distinguish themselves from package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. Here this is __ISBN__. This is then followed by +values detailing the reason for the failure. The full set of __-errorCode__s +which can be thrown by this package are: + + - INVALID ISBN CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be an ISBN. + + - INVALID ISBN CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + + - INVALID ISBN LENGTH + + The input value is of the wrong length to be an ISBN. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Book Number](../../../../index.md#book_number), +[Checking](../../../../index.md#checking), [EAN](../../../../index.md#ean), +[EAN13](../../../../index.md#ean13), [European Article +Number](../../../../index.md#european_article_number), +[ISBN](../../../../index.md#isbn), [International Article +Number](../../../../index.md#international_article_number), [International +Standard Book Number](../../../../index.md#international_standard_book_number), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/valtype/luhn.md Index: embedded/md/tcllib/files/modules/valtype/luhn.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/luhn.md @@ -0,0 +1,133 @@ + +[//000000001]: # (valtype::luhn - Validation types) +[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::luhn(n) 1 tcllib "Validation types") + +# NAME + +valtype::luhn - Validation for plain number with a LUHN checkdigit + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit 2 +package require valtype::common +package require valtype::luhn ?1? + +[__valtype::luhn__ __validate__ *value*](#1) +[__valtype::luhn__ __checkdigit__ *value*](#2) + +# DESCRIPTION + +This package implements a snit validation type for a plain number with a LUHN +checkdigit. + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__, a validation type defined by +the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is +an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + valtype::luhn validate .... ;# Does nothing + valtype::luhn validate .... ;# Throws an error (bad luhn checkdigit). + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error, possibly with additional elements +which provide more details about the problem. + +# API + +The API provided by this package satisfies the specification of snit validation +types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*. + + - __valtype::luhn__ __validate__ *value* + + This method validates the *value* and returns it, possibly in a canonical + form, if it passes. If the value does not pass the validation an error is + thrown. + + - __valtype::luhn__ __checkdigit__ *value* + + This method computes a check digit for the *value*. Before doing so it is + validated, except for a checkdigit. If the value does not pass the + validation no check digit is calculated and an error is thrown instead. + +# Error Codes + +As said in the package description, the errors thrown by the commands of this +package in response to input validation failures use the __-errorcode__ INVALID +to distinguish themselves from package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. Here this is __LUHN__. This is then followed by +values detailing the reason for the failure. The full set of __-errorCode__s +which can be thrown by this package are: + + - INVALID LUHN CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be a plain number with a LUHN + checkdigit. + + - INVALID LUHN CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Checking](../../../../index.md#checking), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa), +[luhn](../../../../index.md#luhn) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/valtype/luhn5.md Index: embedded/md/tcllib/files/modules/valtype/luhn5.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/luhn5.md @@ -0,0 +1,133 @@ + +[//000000001]: # (valtype::luhn5 - Validation types) +[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::luhn5(n) 1 tcllib "Validation types") + +# NAME + +valtype::luhn5 - Validation for plain number with a LUHN5 checkdigit + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit 2 +package require valtype::common +package require valtype::luhn5 ?1? + +[__valtype::luhn5__ __validate__ *value*](#1) +[__valtype::luhn5__ __checkdigit__ *value*](#2) + +# DESCRIPTION + +This package implements a snit validation type for a plain number with a LUHN5 +checkdigit. + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__, a validation type defined by +the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is +an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + valtype::luhn5 validate .... ;# Does nothing + valtype::luhn5 validate .... ;# Throws an error (bad luhn5 checkdigit). + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error, possibly with additional elements +which provide more details about the problem. + +# API + +The API provided by this package satisfies the specification of snit validation +types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*. + + - __valtype::luhn5__ __validate__ *value* + + This method validates the *value* and returns it, possibly in a canonical + form, if it passes. If the value does not pass the validation an error is + thrown. + + - __valtype::luhn5__ __checkdigit__ *value* + + This method computes a check digit for the *value*. Before doing so it is + validated, except for a checkdigit. If the value does not pass the + validation no check digit is calculated and an error is thrown instead. + +# Error Codes + +As said in the package description, the errors thrown by the commands of this +package in response to input validation failures use the __-errorcode__ INVALID +to distinguish themselves from package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. Here this is __LUHN5__. This is then followed by +values detailing the reason for the failure. The full set of __-errorCode__s +which can be thrown by this package are: + + - INVALID LUHN5 CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be a plain number with a LUHN5 + checkdigit. + + - INVALID LUHN5 CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Checking](../../../../index.md#checking), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa), +[luhn](../../../../index.md#luhn), [luhn-5](../../../../index.md#luhn_5) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/valtype/usnpi.md Index: embedded/md/tcllib/files/modules/valtype/usnpi.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/usnpi.md @@ -0,0 +1,139 @@ + +[//000000001]: # (valtype::usnpi - Validation types) +[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::usnpi(n) 1 tcllib "Validation types") + +# NAME + +valtype::usnpi - Validation for USNPI + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit 2 +package require valtype::common +package require valtype::luhn +package require valtype::usnpi ?1? + +[__valtype::usnpi__ __validate__ *value*](#1) +[__valtype::usnpi__ __checkdigit__ *value*](#2) + +# DESCRIPTION + +This package implements a snit validation type for an USNPI. + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__, a validation type defined by +the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is +an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + valtype::usnpi validate .... ;# Does nothing + valtype::usnpi validate .... ;# Throws an error (bad US National Provider Identifier (US-NPI) number). + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error, possibly with additional elements +which provide more details about the problem. + +# API + +The API provided by this package satisfies the specification of snit validation +types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*. + + - __valtype::usnpi__ __validate__ *value* + + This method validates the *value* and returns it, possibly in a canonical + form, if it passes. If the value does not pass the validation an error is + thrown. + + - __valtype::usnpi__ __checkdigit__ *value* + + This method computes a check digit for the *value*. Before doing so it is + validated, except for a checkdigit. If the value does not pass the + validation no check digit is calculated and an error is thrown instead. + +# Error Codes + +As said in the package description, the errors thrown by the commands of this +package in response to input validation failures use the __-errorcode__ INVALID +to distinguish themselves from package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. Here this is __USNPI__. This is then followed by +values detailing the reason for the failure. The full set of __-errorCode__s +which can be thrown by this package are: + + - INVALID USNPI CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be an USNPI. + + - INVALID USNPI CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + + - INVALID USNPI LENGTH + + The input value is of the wrong length to be an USNPI. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Checking](../../../../index.md#checking), [NPI](../../../../index.md#npi), +[National Provider +Identifier](../../../../index.md#national_provider_identifier), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[US-NPI](../../../../index.md#us_npi), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa), +[medicare](../../../../index.md#medicare) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/valtype/valtype_common.md Index: embedded/md/tcllib/files/modules/valtype/valtype_common.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/valtype_common.md @@ -0,0 +1,149 @@ + +[//000000001]: # (valtype::common - Validation types) +[//000000002]: # (Generated from file 'valtype_common.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::common(n) 1 tcllib "Validation types") + +# NAME + +valtype::common - Validation, common code + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require valtype::common ?1? + +[__valtype::common::reject__ *code* *text*](#1) +[__valtype::common::badchar__ *code* ?*text*?](#2) +[__valtype::common::badcheck__ *code* ?*text*?](#3) +[__valtype::common::badlength__ *code* *lengths* ?*text*?](#4) +[__valtype::common::badprefix__ *code* *prefixes* ?*text*?](#5) + +# DESCRIPTION + +This package implements a number of common commands used by the validation types +in this module. These commands essentially encapsulate the throwing of +validation errors, ensuring that a proper __-errorcode__ is used. See section +[Error Codes](#section3). + +# API + + - __valtype::common::reject__ *code* *text* + + The core command of this package it throws an __INVALID__ error with the + specified *text*. The first argument is a list of codes extending the + __INVALID__ with detail information. + + - __valtype::common::badchar__ *code* ?*text*? + + This command throws an __INVALID CHAR__ error with the specified *text*. The + first argument is a list of codes providing details. These are inserted + between the codes __INVALID__ and __CHARACTER__. + + - __valtype::common::badcheck__ *code* ?*text*? + + This command throws an __INVALID CHECK-DIGIT__ error with the specified + *text*, if any, extended by the standard text "the check digit is + incorrect". The first argument is a list of codes providing details. These + are inserted between the codes __INVALID__ and __CHECK_DIGIT__. + + - __valtype::common::badlength__ *code* *lengths* ?*text*? + + This command throws an __INVALID LENGTH__ error with the specified *text*, + if any, extended by the standard text "incorrect length, expected ... + character(s)". The first argument is a list of codes providing details. + These are inserted between the codes __INVALID__ and __LENGTH__. The + argument *lengths* is a list of the input lengths which had been expected, + i.e. these are the valid lengths. + + - __valtype::common::badprefix__ *code* *prefixes* ?*text*? + + This command throws an __INVALID PREFIX__ error with the specified *text*, + if any, extended by the standard text "incorrect prefix, expected ...". The + first argument is a list of codes providing details. These are inserted + between the codes __INVALID__ and __PREFIX__. The argument *prefixes* is a + list of the input prefixes which had been expected, i.e. these are the valid + prefixes. + +# Error Codes + +The errors thrown by the commands of this package all use the __-errorcode__ +__INVALID__ to distinguish the input validation failures they represent from +package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. This is supplied by the caller. This is then followed +by values detailing the reason for the failure. The full set of __-errorCode__s +which can be thrown by this package are shown below, with __<>__ a placeholder +for both the caller-supplied type-information, the type description. + + - INVALID __<>__ CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be a __<>__. + + - INVALID __<>__ CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + + - INVALID __<>__ LENGTH + + The input value is of the wrong length to be a __<>__. + + - INVALID __<>__ PREFIX + + The input value does not start with the magic value(s) required for it to be + a __<>__. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Checking](../../../../index.md#checking), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/valtype/verhoeff.md Index: embedded/md/tcllib/files/modules/valtype/verhoeff.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/valtype/verhoeff.md @@ -0,0 +1,133 @@ + +[//000000001]: # (valtype::verhoeff - Validation types) +[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown') +[//000000003]: # (valtype::verhoeff(n) 1 tcllib "Validation types") + +# NAME + +valtype::verhoeff - Validation for plain number with a VERHOEFF checkdigit + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Error Codes](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require snit 2 +package require valtype::common +package require valtype::verhoeff ?1? + +[__valtype::verhoeff__ __validate__ *value*](#1) +[__valtype::verhoeff__ __checkdigit__ *value*](#2) + +# DESCRIPTION + +This package implements a snit validation type for a plain number with a +VERHOEFF checkdigit. + +A validation type is an object that can be used to validate Tcl values of a +particular kind. For example, __snit::integer__, a validation type defined by +the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is +an integer. + +Every validation type has a __validate__ method which is used to do the +validation. This method must take a single argument, the value to be validated; +further, it must do nothing if the value is valid, but throw an error if the +value is invalid: + + valtype::verhoeff validate .... ;# Does nothing + valtype::verhoeff validate .... ;# Throws an error (bad verhoeff checkdigit). + +The __validate__ method will always return the validated value on success, and +throw the __-errorcode__ INVALID on error, possibly with additional elements +which provide more details about the problem. + +# API + +The API provided by this package satisfies the specification of snit validation +types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*. + + - __valtype::verhoeff__ __validate__ *value* + + This method validates the *value* and returns it, possibly in a canonical + form, if it passes. If the value does not pass the validation an error is + thrown. + + - __valtype::verhoeff__ __checkdigit__ *value* + + This method computes a check digit for the *value*. Before doing so it is + validated, except for a checkdigit. If the value does not pass the + validation no check digit is calculated and an error is thrown instead. + +# Error Codes + +As said in the package description, the errors thrown by the commands of this +package in response to input validation failures use the __-errorcode__ INVALID +to distinguish themselves from package internal errors. + +To provide more detailed information about why the validation failed the +__-errorCode__ goes actually beyond that. First, it will contain a code +detailing the type itself. Here this is __VERHOEFF__. This is then followed by +values detailing the reason for the failure. The full set of __-errorCode__s +which can be thrown by this package are: + + - INVALID VERHOEFF CHARACTER + + The input value contained one or more bad characters, i.e. characters which + must not occur in the input for it to be a plain number with a VERHOEFF + checkdigit. + + - INVALID VERHOEFF CHECK-DIGIT + + The check digit of the input value is wrong. This usually signals a + data-entry error, with digits transposed, forgotten, etc. Of course, th + input may be an outright fake too. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *valtype* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Checking](../../../../index.md#checking), +[Testing](../../../../index.md#testing), [Type +checking](../../../../index.md#type_checking), +[Validation](../../../../index.md#validation), [Value +checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa), +[verhoeff](../../../../index.md#verhoeff) + +# CATEGORY + +Validation, Type checking + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/cat.md Index: embedded/md/tcllib/files/modules/virtchannel_base/cat.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/cat.md @@ -0,0 +1,90 @@ + +[//000000001]: # (tcl::chan::cat - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'cat.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::cat(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::cat - Concatenation channel + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::core ?1? +package require tcl::chan::cat ?1? + +[__::tcl::chan::cat__ *chan*...](#1) + +# DESCRIPTION + +The __tcl::chan::cat__ package provides a command creating concatenation +channels. These are non-seekable channels owning a list of subordinate channels +whose contents they return in order, until all are exhausted. In this manner the +channel is the concatentation of the contents of all the sub-ordinate channels. + +Note that the created channels take ownership of the channels they were +constructed with. Whenever they have exhausted one of their channel it will be +closed. Similarly, closing the cat channel will close all the sub-ordinates it +still has. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::core](../virtchannel_core/core.md)__ framework. + +Event handling is delegated to the currently active sub-channel. + +# API + + - __::tcl::chan::cat__ *chan*... + + This command creates the concatenation channel using all the provided + channels, and returns its handle. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[concatenation channel](../../../../index.md#concatenation_channel), [reflected +channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/facade.md Index: embedded/md/tcllib/files/modules/virtchannel_base/facade.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/facade.md @@ -0,0 +1,118 @@ + +[//000000001]: # (tcl::chan::facade - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'facade.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::facade(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::facade - Facade channel + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require logger +package require tcl::chan::core ?1? +package require tcl::chan::facade ?1? + +[__::tcl::chan::facade__ *chan*](#1) + +# DESCRIPTION + +The __tcl::chan::facade__ package provides a command creating facades to other +channels. These are channels which own a single subordinate channel and delegate +all operations to. + +The main use for facades is the debugging of actions on a channel. While most of +the information could be tracked by a virtual channel transformation it does not +have access to the event-related operation, and furthermore they are only +available in Tcl 8.6. + +Therefore this channel, usable with Tcl 8.5, and having access to everything +going on for a channel. + +The intercepted actions on channel are logged through package +__[logger](../log/logger.md)__. + +Beyond that facades provide the following additional channel configuration +options: + + - __-self__ + + The TclOO object handling the facade. + + - __-fd__ + + The handle of the subordinate, i.e. wrapped channel. + + - __-used__ + + The last time the wrapped channel was read from or written to by the facade, + as per __clock milliseconds__. A value of __0__ indicates that the + subordinate channel was not accessed at all, yet. + + - __-created__ + + The time the facade was created, as per __clock milliseconds__. + + - __-user__ + + A free-form value identifying the user of the facade and its wrapped + channel. + +Of these only option __-user__ is writable. + +# API + + - __::tcl::chan::facade__ *chan* + + This command creates the facade channel around the provided channel *chan*, + and returns its handle. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[concatenation channel](../../../../index.md#concatenation_channel), [reflected +channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/halfpipe.md Index: embedded/md/tcllib/files/modules/virtchannel_base/halfpipe.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/halfpipe.md @@ -0,0 +1,120 @@ + +[//000000001]: # (tcl::chan::halfpipe - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'halfpipe.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::halfpipe(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::halfpipe - In-memory channel, half of a fifo2 + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Options](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::events ?1? +package require tcl::chan::halfpipe ?1? +package require tcl::chan::halfpipe ?1? + +[__::tcl::chan::halfpipe__ ?__-option__ *value*...?](#1) +[*objectCmd* __put__ *bytes*](#2) + +# DESCRIPTION + +The __tcl::chan::halfpipe__ package provides a command creating one half of a +__[tcl::chan::fifo2](tcllib_fifo2.md)__ pair. Writing into such a channel +invokes a set of callbacks which then handle the data. This is similar to a +channel handler, except having a much simpler API. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::events](../virtchannel_core/events.md)__ framework. + +# API + + - __::tcl::chan::halfpipe__ ?__-option__ *value*...? + + This command creates a halfpipe channel and configures it with the callbacks + to run when the channel is closed, data was written to it, or ran empty. See + the section [Options](#section3) for the list of options and associated + semantics. The result of the command is a list containing two elements, the + handle of the new channel, and the object command of the channel handler, in + this order. The latter is supplied to the caller to provide her with access + to the __put__ method for adding data to the channel. + + Two halfpipes with a bit of glue logic in the callbacks make for one + __[tcl::chan::fifo2](tcllib_fifo2.md)__. + + - *objectCmd* __put__ *bytes* + + This method of the channel handler object puts the data *bytes* into the + channel so that it can be read from it. + +# Options + + - __-close-command__ cmdprefix + + This callback is invoked when the channel is closed. A single argument is + supplied, the handle of the channel being closed. The result of the callback + is ignored. + + - __-write-command__ cmdprefix + + This callback is invoked when data is written to the channel. Two arguments + are supplied, the handle of the channel written to, and the data written. + The result of the callback is ignored. + + - __-empty-command__ cmdprefix + + This callback is invoked when the channel has run out of data to read. A + single argument is supplied, the handle of the channel. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[callbacks](../../../../index.md#callbacks), [fifo](../../../../index.md#fifo), +[in-memory channel](../../../../index.md#in_memory_channel), [reflected +channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/nullzero.md Index: embedded/md/tcllib/files/modules/virtchannel_base/nullzero.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/nullzero.md @@ -0,0 +1,86 @@ + +[//000000001]: # (tcl::chan::nullzero - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'nullzero.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::nullzero(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::nullzero - Null/Zero channel combination + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::events ?1? +package require tcl::chan::nullzero ?1? + +[__::tcl::chan::nullzero__](#1) + +# DESCRIPTION + +The __tcl::chan::nullzero__ package provides a command creating channels, which +are a combination of null and zero devices. They immediately forget whatever is +written to them, and on reading return an infinite stream of null characters. + +Packages related to this are __[tcl::chan::null](tcllib_null.md)__ and +__[tcl::chan::zero](tcllib_zero.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::events](../virtchannel_core/events.md)__ framework. + +# API + + - __::tcl::chan::nullzero__ + + This command creates a new nullzero channel and returns its handle. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[/dev/null](../../../../index.md#_dev_null), +[/dev/zero](../../../../index.md#_dev_zero), [null](../../../../index.md#null), +[reflected channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel), +[zero](../../../../index.md#zero) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/randseed.md Index: embedded/md/tcllib/files/modules/virtchannel_base/randseed.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/randseed.md @@ -0,0 +1,85 @@ + +[//000000001]: # (tcl::randomseed - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'randseed.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::randomseed(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::randomseed - Utilities for random channels + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::randomseed ?1? + +[__::tcl::randomseed__](#1) +[__::tcl::combine__ *seed1* *seed2*](#2) + +# DESCRIPTION + +The __tcl::randomseed__ package provides a a few utility commands to help with +the seeding of __[tcl::chan::random](tcllib_random.md)__ channels. + +# API + + - __::tcl::randomseed__ + + This command creates returns a list of seed integers suitable as seed + argument for random channels. The numbers are derived from the process id, + current time, and Tcl random number generator. + + - __::tcl::combine__ *seed1* *seed2* + + This command takes to seed lists and combines them into a single list by + XORing them elementwise, modulo 256. If the lists are not of equial length + the shorter of the two is padded with 0s before merging. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[/dev/random](../../../../index.md#_dev_random), +[merge](../../../../index.md#merge), [random](../../../../index.md#random), +[reflected channel](../../../../index.md#reflected_channel), +[seed](../../../../index.md#seed), [tip 219](../../../../index.md#tip_219), +[virtual channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/std.md Index: embedded/md/tcllib/files/modules/virtchannel_base/std.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/std.md @@ -0,0 +1,84 @@ + +[//000000001]: # (tcl::chan::std - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'std.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::std(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::std - Standard I/O, unification of stdin and stdout + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::core ?1? +package require tcl::chan::std ?1? + +[__::tcl::chan::std__](#1) + +# DESCRIPTION + +The __tcl::chan::std__ package provides a command creating a standard channel +which unifies stdin and stdout into a single read- and writable channel. The +result is not seek-able, like the original standard channels. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::core](../virtchannel_core/core.md)__ framework. + +# API + + - __::tcl::chan::std__ + + This command creates the std channel and returns its handle. + + The channel is created only once, on the first call, and all future calls + simply return this handle. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[reflected channel](../../../../index.md#reflected_channel), [standard +io](../../../../index.md#standard_io), [stdin](../../../../index.md#stdin), +[stdout](../../../../index.md#stdout), [tip 219](../../../../index.md#tip_219), +[virtual channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2011 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo.md @@ -0,0 +1,86 @@ + +[//000000001]: # (tcl::chan::fifo - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'tcllib_fifo.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::fifo(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::fifo - In-memory fifo channel + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::events ?1? +package require tcl::chan::fifo ?1? + +[__::tcl::chan::fifo__](#1) + +# DESCRIPTION + +The __tcl::chan::fifo__ package provides a command creating channels which live +purely in memory. Access is fifo-like, i.e. things are read out of the channel +in the order they were written to it. This is equivalent to the fifo channels +provided by the package __Memchan__, except that this is written in pure Tcl, +not C. On the other hand, __Memchan__ is usable with Tcl 8.4 and before, whereas +this package requires Tcl 8.5 or higher, and +__[TclOO](../../../../index.md#tcloo)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::events](../virtchannel_core/events.md)__ framework. + +# API + + - __::tcl::chan::fifo__ + + This command creates a new fifo channel and returns its handle. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[fifo](../../../../index.md#fifo), [in-memory +channel](../../../../index.md#in_memory_channel), [reflected +channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo2.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo2.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo2.md @@ -0,0 +1,92 @@ + +[//000000001]: # (tcl::chan::fifo2 - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'tcllib_fifo2.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::fifo2(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::fifo2 - In-memory interconnected fifo channels + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::events ?1? +package require tcl::chan::halfpipe ?1? +package require tcl::chan::fifo2 ?1? + +[__::tcl::chan::fifo2__](#1) + +# DESCRIPTION + +The __tcl::chan::fifo2__ package provides a command creating pairs of channels +which live purely in memory and are connected to each other in a fifo manner. +What is written to one half of the pair can be read from the other half, in the +same order. One particular application for this is communication between +threads, with one half of the pair moved to the thread to talk to. This is +equivalent to the fifo2 channels provided by the package __Memchan__, except +that this is written in pure Tcl, not C. On the other hand, __Memchan__ is +usable with Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher, +and __[TclOO](../../../../index.md#tcloo)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::events](../virtchannel_core/events.md)__ framework. + +# API + + - __::tcl::chan::fifo2__ + + This command creates a new connected pair of fifo channels and returns their + handles, as a list containing two elements. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[connected fifos](../../../../index.md#connected_fifos), +[fifo](../../../../index.md#fifo), [in-memory +channel](../../../../index.md#in_memory_channel), [inter-thread +communication](../../../../index.md#inter_thread_communication), [reflected +channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_memchan.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_memchan.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_memchan.md @@ -0,0 +1,87 @@ + +[//000000001]: # (tcl::chan::memchan - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'tcllib_memchan.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::memchan(n) 1.0.4 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::memchan - In-memory channel + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::events ?1? +package require tcl::chan::memchan ?1.0.4? + +[__::tcl::chan::memchan__](#1) + +# DESCRIPTION + +The __tcl::chan::memchan__ package provides a command creating channels which +live purely in memory. They provide random-access, i.e. are seekable. This is +equivalent to the memchan channels provided by the package __Memchan__, except +that this is written in pure Tcl, not C. On the other hand, __Memchan__ is +usable with Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher, +and __[TclOO](../../../../index.md#tcloo)__. + +Packages related to this are __[tcl::chan::string](tcllib_string.md)__ and +__[tcl::chan::variable](tcllib_variable.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::events](../virtchannel_core/events.md)__ framework. + +# API + + - __::tcl::chan::memchan__ + + This command creates a new memchan channel and returns its handle. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[in-memory channel](../../../../index.md#in_memory_channel), [reflected +channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009-2017 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_null.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_null.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_null.md @@ -0,0 +1,87 @@ + +[//000000001]: # (tcl::chan::null - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'tcllib_null.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::null(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::null - Null channel + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::events ?1? +package require tcl::chan::null ?1? + +[__::tcl::chan::null__](#1) + +# DESCRIPTION + +The __tcl::chan::null__ package provides a command creating null channels, i.e. +write-only channels which immediately forget whatever is written to them. This +is equivalent to the null channels provided by the package __Memchan__, except +that this is written in pure Tcl, not C. On the other hand, __Memchan__ is +usable with Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher, +and __[TclOO](../../../../index.md#tcloo)__. + +Packages related to this are __[tcl::chan::zero](tcllib_zero.md)__ and +__[tcl::chan::nullzero](nullzero.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::events](../virtchannel_core/events.md)__ framework. + +# API + + - __::tcl::chan::null__ + + This command creates a new null channel and returns its handle. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[/dev/null](../../../../index.md#_dev_null), [null](../../../../index.md#null), +[reflected channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_random.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_random.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_random.md @@ -0,0 +1,87 @@ + +[//000000001]: # (tcl::chan::random - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'tcllib_random.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::random(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::random - Random channel + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::events ?1? +package require tcl::chan::random ?1? + +[__::tcl::chan::random__ *seed*](#1) + +# DESCRIPTION + +The __tcl::chan::random__ package provides a command creating random channels, +i.e. read-only channels which return an infinite stream of pseudo-random +characters upon reading. This is similar to the random channels provided by the +package __Memchan__, except that this is written in pure Tcl, not C, and uses a +much simpler generator as well. On the other hand, __Memchan__ is usable with +Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher, and TclOO. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::events](../virtchannel_core/events.md)__ framework. + +# API + + - __::tcl::chan::random__ *seed* + + This command creates a new random channel and returns its handle. The seed + is a list of integer numbers used to initialize the internal feedback shift + register of the generator. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[/dev/random](../../../../index.md#_dev_random), +[random](../../../../index.md#random), [reflected +channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_string.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_string.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_string.md @@ -0,0 +1,87 @@ + +[//000000001]: # (tcl::chan::string - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'tcllib_string.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::string(n) 1.0.3 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::string - Read-only in-memory channel + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::events ?1? +package require tcl::chan::string ?1.0.3? + +[__::tcl::chan::string__ *content*](#1) + +# DESCRIPTION + +The __tcl::chan::string__ package provides a command creating channels which +live purely in memory. They provide random-access, i.e. are seekable. In +contrast to the channels created by __[tcl::chan::memchan](tcllib_memchan.md)__ +they are read-only however, their content is provided at the time of +construction and immutable afterward. + +Packages related to this are __[tcl::chan::memchan](tcllib_memchan.md)__ and +__[tcl::chan::variable](tcllib_variable.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::events](../virtchannel_core/events.md)__ framework. + +# API + + - __::tcl::chan::string__ *content* + + This command creates a new string channel and returns its handle. The + channel provides random read-only access to the *content* string. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[in-memory channel](../../../../index.md#in_memory_channel), [reflected +channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_variable.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_variable.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_variable.md @@ -0,0 +1,88 @@ + +[//000000001]: # (tcl::chan::variable - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'tcllib_variable.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::variable(n) 1.0.4 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::variable - In-memory channel using variable for storage + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::events ?1? +package require tcl::chan::variable ?1.0.4? + +[__::tcl::chan::variable__ *varname*](#1) + +# DESCRIPTION + +The __tcl::chan::variable__ package provides a command creating channels which +live purely in memory. They provide random-access, i.e. are seekable. In +contrast to the channels created by __[tcl::chan::memchan](tcllib_memchan.md)__ +the data is not hidden in the channel however, but stored in an associated +variable, specified at the time of construction. + +Packages related to this are __[tcl::chan::memchan](tcllib_memchan.md)__ and +__[tcl::chan::string](tcllib_string.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::events](../virtchannel_core/events.md)__ framework. + +# API + + - __::tcl::chan::variable__ *varname* + + This command creates a new variable channel and returns its handle. The + content of the channel is stored in the associated namespace variable + *varname*. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[in-memory channel](../../../../index.md#in_memory_channel), [reflected +channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_zero.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_zero.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_zero.md @@ -0,0 +1,88 @@ + +[//000000001]: # (tcl::chan::zero - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'tcllib_zero.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::zero(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::zero - Zero channel + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::events ?1? +package require tcl::chan::zero ?1? + +[__::tcl::chan::zero__](#1) + +# DESCRIPTION + +The __tcl::chan::zero__ package provides a command creating zero channels, i.e. +read-only channels which return an infinite stream of null characters upon +reading. This is equivalent to the zero channels provided by the package +__Memchan__, except that this is written in pure Tcl, not C. On the other hand, +__Memchan__ is usable with Tcl 8.4 and before, whereas this package requires Tcl +8.5 or higher, and TclOO. + +Packages related to this are __[tcl::chan::null](tcllib_null.md)__ and +__[tcl::chan::nullzero](nullzero.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::events](../virtchannel_core/events.md)__ framework. + +# API + + - __::tcl::chan::zero__ + + This command creates a new zero channel and returns its handle. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[/dev/zero](../../../../index.md#_dev_zero), [reflected +channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel), +[zero](../../../../index.md#zero) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_base/textwindow.md Index: embedded/md/tcllib/files/modules/virtchannel_base/textwindow.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_base/textwindow.md @@ -0,0 +1,83 @@ + +[//000000001]: # (tcl::chan::textwindow - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'textwindow.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::textwindow(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::textwindow - Textwindow channel + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::events ?1? +package require tcl::chan::textwindow ?1? + +[__::tcl::chan::textwindow__ *widget*](#1) + +# DESCRIPTION + +The __tcl::chan::textwindow__ package provides a command creating write-only +channels connected to text widgets. Anything written to the channel is printed +into the associated widget. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +channel handler is a sub-class of the +__[tcl::chan::events](../virtchannel_core/events.md)__ framework. + +# API + + - __::tcl::chan::textwindow__ *widget* + + This command creates a new textwindow channel and returns its handle. Data + written to this channel will appear in the associated *widget*. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[Tk](../../../../index.md#tk), [reflected +channel](../../../../index.md#reflected_channel), [text +widget](../../../../index.md#text_widget), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_core/core.md Index: embedded/md/tcllib/files/modules/virtchannel_core/core.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_core/core.md @@ -0,0 +1,116 @@ + +[//000000001]: # (tcl::chan::core - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'core.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::core(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::core - Basic reflected/virtual channel support + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Class API](#section2) + + - [Instance API](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::core ?1? + +[__::tcl::chan::core__ *objectName*](#1) +[*objectName* __initialize__ *thechannel* *mode*](#2) +[*objectName* __finalize__ *thechannel*](#3) +[*objectName* __destroy__](#4) + +# DESCRIPTION + +The __tcl::chan::core__ package provides a +__[TclOO](../../../../index.md#tcloo)__ class implementing common behaviour +needed by virtually every reflected or virtual channel (initialization, +finalization). + +This class expects to be used as either superclass of a concrete channel class, +or to be mixed into such a class. + +# Class API + + - __::tcl::chan::core__ *objectName* + + This command creates a new channel core object with an associated global Tcl + command whose name is *objectName*. This command may be used to invoke + various operations on the object, as described in the section for the + [Instance API](#section3). + +# Instance API + +The API of channel core instances provides only two methods, both corresponding +to channel handler commands (For reference see [TIP 219](http:/tip.tcl.tk/219)). +They expect to be called from whichever object instance the channel core was +made a part of. + + - *objectName* __initialize__ *thechannel* *mode* + + This method implements standard behaviour for the __initialize__ method of + channel handlers. Using introspection it finds the handler methods supported + by the instance and returns a list containing their names, as expected by + the support for reflected channels in the Tcl core. + + It further remembers the channel handle in an instance variable for access + by sub-classes. + + - *objectName* __finalize__ *thechannel* + + This method implements standard behaviour for the __finalize__ method of + channel handlers. It simply destroys itself. + + - *objectName* __destroy__ + + Destroying the channel core instance closes the channel it was initialized + for, see the method __initialize__. When destroyed from within a call of + __finalize__ this does not happen, under the assumption that the channel is + being destroyed by Tcl. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[reflected channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_core/events.md Index: embedded/md/tcllib/files/modules/virtchannel_core/events.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_core/events.md @@ -0,0 +1,124 @@ + +[//000000001]: # (tcl::chan::events - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'events.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::chan::events(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::chan::events - Event support for reflected/virtual channels + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Class API](#section2) + + - [Instance API](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::chan::core ?1? +package require tcl::chan::events ?1? + +[__::tcl::chan::events__ *objectName*](#1) +[*objectName* __finalize__ *thechannel*](#2) +[*objectName* __watch__ *thechannel* *eventmask*](#3) +[*objectName* __allow__ *eventname*...](#4) +[*objectName* __disallow__ *eventname*...](#5) + +# DESCRIPTION + +The __tcl::chan::events__ package provides a +__[TclOO](../../../../index.md#tcloo)__ class implementing common behaviour +needed by virtually every reflected or virtual channel supporting event driven +IO. It is a sub-class of __[tcl::chan::core](core.md)__, inheriting all of its +behaviour. + +This class expects to be used as either superclass of a concrete channel class, +or to be mixed into such a class. + +# Class API + + - __::tcl::chan::events__ *objectName* + + This command creates a new channel event core object with an associated + global Tcl command whose name is *objectName*. This command may be used to + invoke various operations on the object, as described in the section for the + [Instance API](#section3). + +# Instance API + +The API of channel event core instances provides only four methods, two +corresponding to channel handler commands (For reference see [TIP +219](http:/tip.tcl.tk/219)), and the other two for use by sub-classes to control +event generation. They former expect to be called from whichever object instance +the channel event core was made a part of. + + - *objectName* __finalize__ *thechannel* + + This method implements standard behaviour for the __finalize__ method of + channel handlers. It overrides the behaviour inherited from + __[tcl::chan::core](core.md)__ and additionally disables any and all event + generation before destroying itself. + + - *objectName* __watch__ *thechannel* *eventmask* + + This method implements standard behaviour for the __watch__ method of + channel handlers. Called by the IO system whenever the interest in event + changes it updates the instance state to activate and/or suppress the + generation of the events of (non-)interest. + + - *objectName* __allow__ *eventname*... + + - *objectName* __disallow__ *eventname*... + + These two methods are exported to sub-classes, so that their instances can + notify their event core of the events the channel they implement can (allow) + or cannot (disallow) generate. Together with the information about the + events requested by Tcl's IO system coming in through the __watch__ method + the event core is able to determine which events it should (not) generate + and act accordingly. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[event management](../../../../index.md#event_management), [reflected +channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_core/transformcore.md Index: embedded/md/tcllib/files/modules/virtchannel_core/transformcore.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_core/transformcore.md @@ -0,0 +1,116 @@ + +[//000000001]: # (tcl::transform::core - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'transformcore.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::core(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::core - Basic reflected/virtual channel transform support + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Class API](#section2) + + - [Instance API](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.5 +package require TclOO +package require tcl::transform::core ?1? + +[__::tcl::transform::core__ *objectName*](#1) +[*objectName* __initialize__ *thechannel* *mode*](#2) +[*objectName* __finalize__ *thechannel*](#3) +[*objectName* __destroy__](#4) + +# DESCRIPTION + +The __tcl::transform::core__ package provides a +__[TclOO](../../../../index.md#tcloo)__ class implementing common behaviour +needed by virtually every reflected or virtual channel transformation +(initialization, finalization). + +This class expects to be used as either superclass of a concrete channel class, +or to be mixed into such a class. + +# Class API + + - __::tcl::transform::core__ *objectName* + + This command creates a new transform core object with an associated global + Tcl command whose name is *objectName*. This command may be used to invoke + various operations on the object, as described in the section for the + [Instance API](#section3). + +# Instance API + +The API of transform core instances provides only two methods, both +corresponding to transform handler commands (For reference see [TIP +230](http:/tip.tcl.tk/230)). They expect to be called from whichever object +instance the transform core was made a part of. + + - *objectName* __initialize__ *thechannel* *mode* + + This method implements standard behaviour for the __initialize__ method of + transform handlers. Using introspection it finds the handler methods + supported by the instance and returns a list containing their names, as + expected by the support for reflected transformation in the Tcl core. + + It further remembers the channel handle in an instance variable for access + by sub-classes. + + - *objectName* __finalize__ *thechannel* + + This method implements standard behaviour for the __finalize__ method of + channel handlers. It simply destroys itself. + + - *objectName* __destroy__ + + Destroying the transform core instance closes the channel and transform it + was initialized for, see the method __initialize__. When destroyed from + within a call of __finalize__ this does not happen, under the assumption + that the channel and transform are being destroyed by Tcl. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[reflected channel](../../../../index.md#reflected_channel), [tip +219](../../../../index.md#tip_219), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_transform/adler32.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/adler32.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_transform/adler32.md @@ -0,0 +1,110 @@ + +[//000000001]: # (tcl::transform::adler32 - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'adler32.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::adler32(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::adler32 - Adler32 transformation + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require tcl::transform::core ?1? +package require tcl::transform::adler32 ?1? + +[__::tcl::transform::adler32__ *chan* __-option__ *value*...](#1) + +# DESCRIPTION + +The __tcl::transform::adler32__ package provides a command creating a channel +transformation which passes the read and written bytes through unchanged (like +__[tcl::transform::identity](identity.md)__), but additionally continuously +computes the adler32 checksums of the data it has seen for each direction and +stores them in Tcl variables specified at construction time. + +Related transformations in this module are +__[tcl::transform::counter](vt_counter.md)__, +__[tcl::transform::crc32](vt_crc32.md)__, +__[tcl::transform::identity](identity.md)__, and +__[tcl::transform::observe](observe.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +transform handler is a sub-class of the +__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework. + +# API + + - __::tcl::transform::adler32__ *chan* __-option__ *value*... + + This command creates an adler32 checksumming transformation on top of the + channel *chan* and returns its handle. The accepted options are + + * __-read-variable__ varname + + The value of the option is the name of a global or namespaced variable, + the location where the transformation has to store the adler32 checksum + of the data read from the channel. + + If not specified, or the empty string, the checksum of the read + direction is not saved. + + * __-write-variable__ varname + + The value of the option is the name of a global or namespaced variable, + the location where the transformation has to store the adler32 checksum + of the data written to the channel. + + If not specified, or the empty string, the checksum of the write + direction is not saved. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[adler32](../../../../index.md#adler32), [channel +transformation](../../../../index.md#channel_transformation), +[checksum](../../../../index.md#checksum), [reflected +channel](../../../../index.md#reflected_channel), [tip +230](../../../../index.md#tip_230), +[transformation](../../../../index.md#transformation), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_transform/hex.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/hex.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_transform/hex.md @@ -0,0 +1,86 @@ + +[//000000001]: # (tcl::transform::hex - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'hex.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::hex(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::hex - Hexadecimal encoding transformation + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require tcl::transform::core ?1? +package require tcl::transform::hex ?1? + +[__::tcl::transform::hex__ *chan*](#1) + +# DESCRIPTION + +The __tcl::transform::hex__ package provides a command creating a channel +transformation which hex encodes data written to it, and decodes the data read +from it. + +A related transformations in this module is +__[tcl::transform::base64](vt_base64.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +transform handler is a sub-class of the +__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework. + +# API + + - __::tcl::transform::hex__ *chan* + + This command creates a hex transformation on top of the channel *chan* and + returns its handle. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel transformation](../../../../index.md#channel_transformation), +[hexadecimal](../../../../index.md#hexadecimal), [reflected +channel](../../../../index.md#reflected_channel), [tip +230](../../../../index.md#tip_230), +[transformation](../../../../index.md#transformation), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_transform/identity.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/identity.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_transform/identity.md @@ -0,0 +1,91 @@ + +[//000000001]: # (tcl::transform::identity - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'identity.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::identity(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::identity - Identity transformation + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require tcl::transform::core ?1? +package require tcl::transform::identity ?1? + +[__::tcl::transform::identity__ *chan*](#1) + +# DESCRIPTION + +The __tcl::transform::identity__ package provides a command creating an identity +channel transformation, which does nothing but pass the read and written bytes +through it unchanged. Not really useful in an application, however as the +prototypical observer transformation its code is a useful starting point for any +other observers people may wish to write. + +The transformations in this module which derived from identity's code are +__[tcl::transform::adler32](adler32.md)__, +__[tcl::transform::counter](vt_counter.md)__, +__[tcl::transform::crc32](vt_crc32.md)__, and +__[tcl::transform::observe](observe.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +transform handler is a sub-class of the +__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework. + +# API + + - __::tcl::transform::identity__ *chan* + + This command creates an identity transformation on top of the channel *chan* + and returns its handle. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel transformation](../../../../index.md#channel_transformation), +[identity](../../../../index.md#identity), [reflected +channel](../../../../index.md#reflected_channel), [tip +230](../../../../index.md#tip_230), +[transformation](../../../../index.md#transformation), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_transform/limitsize.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/limitsize.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_transform/limitsize.md @@ -0,0 +1,88 @@ + +[//000000001]: # (tcl::transform::limitsize - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'limitsize.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::limitsize(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::limitsize - limiting input + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require tcl::transform::core ?1? +package require tcl::transform::limitsize ?1? + +[__::tcl::transform::limitsize__ *chan* *max*](#1) + +# DESCRIPTION + +The __tcl::transform::limitsize__ package provides a command creating a channel +transformation which limits the number of characters which can be read from the +channel. A generator for an artificial EOF. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +transform handler is a sub-class of the +__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework. + +# API + + - __::tcl::transform::limitsize__ *chan* *max* + + This command creates a size limiting transformation on top of the channel + *chan* and returns its handle. + + *max* is the number of bytes which can be read from the channel before EOF + is signaled by the transformation. Note that popping the transformation + clears the EOF it generated as well. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel transformation](../../../../index.md#channel_transformation), +[limitsize](../../../../index.md#limitsize), [reflected +channel](../../../../index.md#reflected_channel), [size +limit](../../../../index.md#size_limit), [tip +230](../../../../index.md#tip_230), +[transformation](../../../../index.md#transformation), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_transform/observe.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/observe.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_transform/observe.md @@ -0,0 +1,92 @@ + +[//000000001]: # (tcl::transform::observe - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'observe.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::observe(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::observe - Observer transformation, stream copy + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require tcl::transform::core ?1? +package require tcl::transform::observe ?1? + +[__::tcl::transform::observe__ *chan* *logw* *logr*](#1) + +# DESCRIPTION + +The __tcl::transform::observer__ package provides a command creating a channel +transformation which passes the read and written bytes through unchanged (like +__[tcl::transform::identity](identity.md)__), but additionally copies the data +it has seen for each direction into channels specified at construction time. + +Related transformations in this module are +__[tcl::transform::adler32](adler32.md)__, +__[tcl::transform::counter](vt_counter.md)__, +__[tcl::transform::crc32](vt_crc32.md)__, and +__[tcl::transform::identity](identity.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +transform handler is a sub-class of the +__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework. + +# API + + - __::tcl::transform::observe__ *chan* *logw* *logr* + + This command creates an observer transformation on top of the channel *chan* + and returns its handle. The channel handles *logr* and *logw* are there the + data is copied to. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel transformation](../../../../index.md#channel_transformation), +[observer](../../../../index.md#observer), [reflected +channel](../../../../index.md#reflected_channel), [stream +copy](../../../../index.md#stream_copy), [tip +230](../../../../index.md#tip_230), +[transformation](../../../../index.md#transformation), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_transform/rot.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/rot.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_transform/rot.md @@ -0,0 +1,98 @@ + +[//000000001]: # (tcl::transform::rot - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'rot.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::rot(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::rot - rot-encryption + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require tcl::transform::core ?1? +package require tcl::transform::rot ?1? + +[__::tcl::transform::rot__ *chan* *key*](#1) + +# DESCRIPTION + +The __tcl::transform::rot__ package provides a command creating a channel +transformation which performs primitive encryption (on writing) and decryption +(on reading) on the alphabetic characters. The algorithm is the Caesar-cipher, a +specific variant of which is rot13. + +A related transformations in this module is +__[tcl::transform::otp](vt_otp.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +transform handler is a sub-class of the +__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework. + +# API + + - __::tcl::transform::rot__ *chan* *key* + + This command creates a rot encryption transformation on top of the channel + *chan* and returns its handle. + + The "*key*" specifies how far characters are rotated in the alphabet, and is + wrapped to the range "0...25". + + Note that this transformation affects only bytes in the ranges ASCII + 65...90, and 97...122, i.e. the upper- and lower-case alphabetic characters, + i.e. "A...Z" and "a...z". All other bytes are passed through unchanged. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[caesar cipher](../../../../index.md#caesar_cipher), [channel +transformation](../../../../index.md#channel_transformation), +[cipher](../../../../index.md#cipher), +[decryption](../../../../index.md#decryption), +[encryption](../../../../index.md#encryption), [reflected +channel](../../../../index.md#reflected_channel), +[rot](../../../../index.md#rot), [rot13](../../../../index.md#rot13), [tip +230](../../../../index.md#tip_230), +[transformation](../../../../index.md#transformation), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_transform/spacer.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/spacer.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_transform/spacer.md @@ -0,0 +1,88 @@ + +[//000000001]: # (tcl::transform::spacer - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'spacer.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::spacer(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::spacer - Space insertation and removal + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require tcl::transform::core ?1? +package require tcl::transform::spacer ?1? + +[__::tcl::transform::spacer__ *chan* *n* ?*space*?](#1) + +# DESCRIPTION + +The __tcl::transform::spacer__ package provides a command creating a channel +transformation which adds spacing to the data written to it, and removes such +spacing from the data read from it. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +transform handler is a sub-class of the +__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework. + +# API + + - __::tcl::transform::spacer__ *chan* *n* ?*space*? + + This command creates a spacer transformation on top of the channel *chan* + and returns its handle. + + The *space* character sequence will be added every *n* bytes of data + written, and on the read side the same is done in reverse, removing the + spacing. If *space* is not specified it defaults to a single space character + (ASCII 32). + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel transformation](../../../../index.md#channel_transformation), +[reflected channel](../../../../index.md#reflected_channel), +[spacing](../../../../index.md#spacing), [tip +230](../../../../index.md#tip_230), +[transformation](../../../../index.md#transformation), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_transform/tcllib_zlib.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/tcllib_zlib.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_transform/tcllib_zlib.md @@ -0,0 +1,88 @@ + +[//000000001]: # (tcl::transform::zlib - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'tcllib_zlib.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::zlib(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::zlib - zlib (de)compression + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require tcl::transform::core ?1? +package require tcl::transform::zlib ?1? + +[__::tcl::transform::zlib__ *chan* ?*level*?](#1) + +# DESCRIPTION + +The __tcl::transform::zlib__ package provides a command creating a channel +transformation which zlib compresses the written data, and decompresses on +reading. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +transform handler is a sub-class of the +__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework. + +# API + + - __::tcl::transform::zlib__ *chan* ?*level*? + + This command creates a zlib compressor transformation on top of the channel + *chan* and returns its handle. + + The *level* specifies how much effort is put into the compression, from + __0__ to __9__, and defaults to __4__. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel transformation](../../../../index.md#channel_transformation), +[compression](../../../../index.md#compression), +[decompression](../../../../index.md#decompression), [reflected +channel](../../../../index.md#reflected_channel), [tip +230](../../../../index.md#tip_230), [tip 234](../../../../index.md#tip_234), +[transformation](../../../../index.md#transformation), [virtual +channel](../../../../index.md#virtual_channel), +[zlib](../../../../index.md#zlib) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_transform/vt_base64.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/vt_base64.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_transform/vt_base64.md @@ -0,0 +1,85 @@ + +[//000000001]: # (tcl::transform::base64 - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'vt_base64.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::base64(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::base64 - Base64 encoding transformation + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require tcl::transform::core ?1? +package require tcl::transform::base64 ?1? + +[__::tcl::transform::base64__ *chan*](#1) + +# DESCRIPTION + +The __tcl::transform::base64__ package provides a command creating a channel +transformation which base64 encodes data written to it, and decodes the data +read from it. + +A related transformations in this module is __[tcl::transform::hex](hex.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +transform handler is a sub-class of the +__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework. + +# API + + - __::tcl::transform::base64__ *chan* + + This command creates a base64 transformation on top of the channel *chan* + and returns its handle. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[base64](../../../../index.md#base64), [channel +transformation](../../../../index.md#channel_transformation), [reflected +channel](../../../../index.md#reflected_channel), [tip +230](../../../../index.md#tip_230), [tip 317](../../../../index.md#tip_317), +[transformation](../../../../index.md#transformation), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_transform/vt_counter.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/vt_counter.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_transform/vt_counter.md @@ -0,0 +1,109 @@ + +[//000000001]: # (tcl::transform::counter - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'vt_counter.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::counter(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::counter - Counter transformation + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require tcl::transform::core ?1? +package require tcl::transform::counter ?1? + +[__::tcl::transform::counter__ *chan* __-option__ *value*...](#1) + +# DESCRIPTION + +The __tcl::transform::counterr__ package provides a command creating a channel +transformation which passes the read and written bytes through unchanged (like +__[tcl::transform::identity](identity.md)__), but additionally counts the bytes +it has seen for each direction and stores these counts in Tcl variables +specified at construction time. + +Related transformations in this module are +__[tcl::transform::adler32](adler32.md)__, +__[tcl::transform::crc32](vt_crc32.md)__, +__[tcl::transform::identity](identity.md)__, and +__[tcl::transform::observe](observe.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +transform handler is a sub-class of the +__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework. + +# API + + - __::tcl::transform::counter__ *chan* __-option__ *value*... + + This command creates a counter transformation on top of the channel *chan* + and returns its handle. The accepted options are + + * __-read-variable__ varname + + The value of the option is the name of a global or namespaced variable, + the location where the transformation has to store the byte count of the + data read from the channel. + + If not specified, or the empty string, the counter of the read direction + is not saved. + + * __-write-variable__ varname + + The value of the option is the name of a global or namespaced variable, + the location where the transformation has to store the byte count of the + data written to the channel. + + If not specified, or the empty string, the counter of the write + direction is not saved. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel transformation](../../../../index.md#channel_transformation), +[counter](../../../../index.md#counter), [reflected +channel](../../../../index.md#reflected_channel), [tip +230](../../../../index.md#tip_230), +[transformation](../../../../index.md#transformation), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_transform/vt_crc32.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/vt_crc32.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_transform/vt_crc32.md @@ -0,0 +1,110 @@ + +[//000000001]: # (tcl::transform::crc32 - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'vt_crc32.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::crc32(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::crc32 - Crc32 transformation + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require tcl::transform::core ?1? +package require tcl::transform::crc32 ?1? + +[__::tcl::transform::crc32__ *chan* __-option__ *value*...](#1) + +# DESCRIPTION + +The __tcl::transform::crc32__ package provides a command creating a channel +transformation which passes the read and written bytes through unchanged (like +__[tcl::transform::identity](identity.md)__), but additionally continuously +computes the crc32 checksums of the data it has seen for each direction and +stores them in Tcl variables specified at construction time. The checksum in +question is zlib's crc32. + +Related transformations in this module are +__[tcl::transform::adler32](adler32.md)__, +__[tcl::transform::counter](vt_counter.md)__, +__[tcl::transform::identity](identity.md)__, and +__[tcl::transform::observe](observe.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +transform handler is a sub-class of the +__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework. + +# API + + - __::tcl::transform::crc32__ *chan* __-option__ *value*... + + This command creates a crc32 checksumming transformation on top of the + channel *chan* and returns its handle. The accepted options are + + * __-read-variable__ varname + + The value of the option is the name of a global or namespaced variable, + the location where the transformation has to store the crc32 checksum of + the data read from the channel. + + If not specified, or the empty string, the checksum of the read + direction is not saved. + + * __-write-variable__ varname + + The value of the option is the name of a global or namespaced variable, + the location where the transformation has to store the crc32 checksum of + the data written to the channel. + + If not specified, or the empty string, the checksum of the write + direction is not saved. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel transformation](../../../../index.md#channel_transformation), +[checksum](../../../../index.md#checksum), [crc32](../../../../index.md#crc32), +[reflected channel](../../../../index.md#reflected_channel), [tip +230](../../../../index.md#tip_230), +[transformation](../../../../index.md#transformation), [virtual +channel](../../../../index.md#virtual_channel) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/virtchannel_transform/vt_otp.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/vt_otp.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/virtchannel_transform/vt_otp.md @@ -0,0 +1,92 @@ + +[//000000001]: # (tcl::transform::otp - Reflected/virtual channel support) +[//000000002]: # (Generated from file 'vt_otp.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcl::transform::otp(n) 1 tcllib "Reflected/virtual channel support") + +# NAME + +tcl::transform::otp - Encryption via one-time pad + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require tcl::transform::core ?1? +package require tcl::transform::otp ?1? + +[__::tcl::transform::otp__ *chan* *keychanw* *keychanr*](#1) + +# DESCRIPTION + +The __tcl::transform::otp__ package provides a command creating a channel +transformation which uses externally provided one-time pads to perform +encryption (on writing) and decryption (on reading). + +A related transformations in this module is __[tcl::transform::rot](rot.md)__. + +The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the +transform handler is a sub-class of the +__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework. + +# API + + - __::tcl::transform::otp__ *chan* *keychanw* *keychanr* + + This command creates a one-time pad based encryption transformation on top + of the channel *chan* and returns its handle. + + The two channels *keychanw* and *keychanr* contain the one-time pads for the + write and read directions, respectively. Their contents are reads and xored + with the bytes written to and read from the channel. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *virtchannel* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[channel transformation](../../../../index.md#channel_transformation), +[cipher](../../../../index.md#cipher), +[decryption](../../../../index.md#decryption), +[encryption](../../../../index.md#encryption), [one time +pad](../../../../index.md#one_time_pad), [otp](../../../../index.md#otp), +[reflected channel](../../../../index.md#reflected_channel), [tip +230](../../../../index.md#tip_230), +[transformation](../../../../index.md#transformation), [virtual +channel](../../../../index.md#virtual_channel), [xor](../../../../index.md#xor) + +# CATEGORY + +Channels + +# COPYRIGHT + +Copyright © 2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/websocket/websocket.md Index: embedded/md/tcllib/files/modules/websocket/websocket.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/websocket/websocket.md @@ -0,0 +1,495 @@ + +[//000000001]: # (websocket - websocket client and server) +[//000000002]: # (Generated from file 'websocket.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (websocket(n) 1.3.1 tcllib "websocket client and server") + +# NAME + +websocket - Tcl implementation of the websocket protocol + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Callbacks](#section2) + + - [API](#section3) + + - [Examples](#section4) + + - [TLS Security Considerations](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Category](#category) + +# SYNOPSIS + +package require Tcl 8.4 +package require http 2.7 +package require logger +package require sha1 +package require base64 +package require websocket ?1.3.1? + +[__::websocket::open__ *url* *handler* ?*options*?](#1) +[__::websocket::send__ *sock* *type* ?*msg*? ?*final*?](#2) +[__::websocket::server__ *sock*](#3) +[__::websocket::live__ *sock* *path* *cb* ?*proto*?](#4) +[__::websocket::test__ *srvSock* *cliSock* *path* ?*hdrs*? ?*qry*?](#5) +[__::websocket::upgrade__ *sock*](#6) +[__::websocket::takeover__ *sock* *handler* ?*server*?](#7) +[__::websocket::conninfo__ *sock* *what*](#8) +[__::websocket::find__ ?*host*? ?*port*?](#9) +[__::websocket::configure__ *sock* *args*](#10) +[__::websocket::loglevel__ ?*loglvl*?](#11) +[__::websocket::close__ *sock* ?*code*? ?*reason*?](#12) + +# DESCRIPTION + +NOTE: THIS DOCUMENTATION IS WORK IN PROGRESS... + +The websocket library is a pure Tcl implementation of the WebSocket +specification covering the needs of both clients and servers. Websockets provide +a way to upgrade a regular HTTP connection into a long-lived and continuous +binary or text communication between the client and the server. The library +offers a high-level interface to receive and send data as specified in RFC 6455 +(v. 13 of the protocol), relieving callers from all necessary protocol framing +and reassembly. It implements the ping facility specified by the standard, +together with levers to control it. Pings are server-driven and ensure the +liveness of the connection across home (NAT) networks. The library has a number +of introspection facilities to inquire about the current state of the +connection, but also to receive notifications of incoming pings, if necessary. +Finally, the library contains a number of helper procedures to facilitate the +upgrading handshaking in existing web servers. + +Central to the library is the procedure __websocket::takeover__ that will take +over a regular socket and treat it as a WebSocket, thus performing all necessary +protocol framing, packetisation and reassembly in servers and clients. The +procedure also takes a handler, a command that will be called back each time a +(possibly reassembled) packet from the remote end is ready for delivery at the +original caller. While exported by the package, the command +__websocket::takeover__ is seldom called in applications, since the package +provides other commands that are specifically tuned for the needs of clients and +servers. + +Typically, clients will open a connection to a remote server by providing a +WebSocket URL (*ws:* or *wss:* schemes) and the handler described above to the +command __websocket::open__. The opening procedure is a wrapper around the +latest http::geturl implementations: it arranges to keep the socket created +within the http library opened for reuse, but confiscates it from its (internal) +map of known sockets for its own use. + +Servers will start by registering themselves through the command +__::websocket::server__ and a number of handlers for paths using the command +__::websocket::live__. Then for each incoming client connection, they should +test the incoming request to detect if it is an upgrade request using +__::websocket::test__ and perform the final handshake to place the socket +connection under the control of the websocket library and its central procedure +using __::websocket::upgrade__. + +Apart from these main commands, the package provides a number of commands for +introspection and basic operations on the websockets that it has under its +control. As WebSockets connections are long-lived, most remaining communication +with the library will be by way of callbacks, i.e. commands that are triggered +whenever important events within the library have occur, but mostly whenever +data has been received on a WebSocket. + +# Callbacks + +A number of commands of the library take a handler handler command as an +argument, a command which will be called back upon reception of data, but also +upon important events within the library or events resulting from control +messages sent by the remote end. For each callback being performed, the +following arguments will be appended: + + - *sock* + + The identifier of the WebSocket, as returned for example by + __::websocket::open__ + + - *type* + + A textual type describing the event or message content, can be one of the + following + + * __text__ + + Complete text message + + * __binary__ + + Complete binary message + + * __ping__ + + Incoming ping message + + * __connect__ + + Notification of successful connection to server + + * __disconnect__ + + Disconnection from remote end + + * __close__ + + Pending closure of connection + + - *msg* + + Will contain the data of the message, whenever this is relevant, i.e. when + the *type* is __text__, __binary__ or __ping__ and whenever there is data + available. + +# API + + - __::websocket::open__ *url* *handler* ?*options*? + + This command is used in clients to open a WebSocket to a remote + websocket-enabled HTTP server. The URL provided as an argument in *url* + should start with ws: or wss:, which are the WebSockets counterpart of http: + and https:. The *handler* is a command that will be called back on data + reception or whenever important events occur during the life of the + websocket. __::websocket::open__ will return a socket which serves as both + the identifier of the websocket and of the physical low-level socket to the + server. This socket can be used in a number of other commands for + introspection or for controlling the behaviour of the library. Being + essentially a wrapper around the __::http::geturl__ command, this command + provides mostly the same set of dash-led options than __::http::geturl__. + Documented below are the options that differ from __::http::geturl__ and + which are specific to the WebSocket library. + + * -headers + + This option is supported, knowing that a number of headers will be + automatically added internally in the library in order to be able to + handshake the upgrading of the socket from a regular HTTP socket to a + WebSocket with the server. + + * -validate + + This option is not supported as it has no real point for WebSockets. + + * -handler + + This option is used internally by the websocket library and cannot be + used. + + * -command + + This option is used internally by the websocket library and cannot be + used. + + * -protocol + + This option specifies a list of application protocols to handshake with + the server. This protocols might help the server triggering application + specific features. + + * -timeout + + This option is supported, but will implemented as part of the library to + enable a number of finalising cleanups. + + - __::websocket::send__ *sock* *type* ?*msg*? ?*final*? + + This command will send a fragment or a control message to the remote end of + the WebSocket identified by *sock*. The type of the message specified in + *type* can either be an integer according to the specification or + (preferrably) one of the following case insensitive strings: "text", + "binary" or "ping". The content of the message to send to the remote end is + contained in *msg* and message fragmentation is made possible by the setting + the argument *final* to non-true, knowing that the type of each fragment has + then to be the same. The command returns the number of bytes that were + effectively sent, or -1 on errors. Serious errors, such as when *sock* does + not identify a known WebSocket or when the connection is not stable yet will + generate errors that must be catched. + + - __::websocket::server__ *sock* + + This command registers the (accept) socket *sock* as the identifier fo an + HTTP server that is capable of doing WebSockets. Paths onto which this + server will listen for incoming connections should be declared using + __::websocket::live__. + + - __::websocket::live__ *sock* *path* *cb* ?*proto*? + + This procedure registers callbacks that will be performed on a WebSocket + compliant server registered with __::websocket::server__ whenever a client + connects to a matching path and protocol. *sock* is the listening socket of + the websocket compliant server declared using __::websocket::server__. + *path* is a glob-style path to match in client request, whenever this will + occur. *cb* is the command to callback (see Callbacks). *proto* is a + glob-style protocol name matcher. + + - __::websocket::test__ *srvSock* *cliSock* *path* ?*hdrs*? ?*qry*? + + This procedure will test if the connection from an incoming client on socket + *cliSock* and on the path *path* is the opening of a WebSocket stream within + a known server *srvSock*. The incoming request is not upgraded at once, + instead a (temporary) context for the incoming connection is created. This + allows server code to perform a number of actions, if necessary, before the + WebSocket stream connection goes live. The text is made by analysing the + content of the headers *hdrs* which should contain a dictionary list of the + HTTP headers of the incoming client connection. The command will return + __1__ if this is an incoming WebSocket upgrade request and __0__ otherwise. + + - __::websocket::upgrade__ *sock* + + Upgrade the socket *sock* that had been deemed by __::websocket::test__ to + be a WebSocket connection request to a true WebSocket as recognised by this + library. As a result, the necessary connection handshake will be sent to the + client, and the command will arrange for relevant callbacks to be made + during the life of the WebSocket, notably using the specifications described + by __::websocket::live__. + + - __::websocket::takeover__ *sock* *handler* ?*server*? + + Take over the existing opened socket *sock* to implement sending and + receiving WebSocket framing on top of the socket. The procedure arranges for + *handler* to be called back whenever messages, control messages or other + important internal events are received or occured. *server* defaults to + __0__ and can be set to __1__ (or a boolean that evaluates to true) to + specify that this is a WebSocket within a server. Apart from specificities + in the protocol, servers should ping their clients at regular intervals in + order to keep the connection opened at all time. When *server* is set to + true, the library will arrange to send these pings automatically. + + - __::websocket::conninfo__ *sock* *what* + + Provides callers with some introspection facilities in order to get some + semi-internal information about an existing websocket connection. Depending + on the value of the *what* argument, the procedure returns the following + piece of information: + + * __peername__ + + Name (preferred) or IP of remote end. + + * __sockname__ + + or __name__ Name or IP of local end. + + * __closed__ + + __1__ if the connection is closed, __0__ otherwise + + * __client__ + + __1__ if the connection is a client websocket, __0__ otherwise + + * __server__ + + __1__ if the connection is a server websocket, __0__ otherwise + + * __type__ + + __server__ if the connection is a server websocket, __client__ + otherwise. + + * __handler__ + + The handler command associated to the websocket + + * __state__ + + The state of the websocket, which can be one of: + + + __CONNECTING__ + + Connection to remote end is in progress. + + + __CONNECTED__ + + Connection is connected to remote end. + + + __CLOSED__ + + Connection is closed. + + - __::websocket::find__ ?*host*? ?*port*? + + Look among existing websocket connections for the ones that match the + hostname and port number filters passed as parameters. This lookup takes the + remote end into account and the *host* argument is matched both against the + hostname (whenever available) and the IP address of the remote end. Both the + *host* and *port* arguments are glob-style string matching filters and + default to __*__, i.e. will match any host and/or port number. + + - __::websocket::configure__ *sock* *args* + + This command takes a number of dash-led options (and their values) to + configure the behaviour of an existing websocket connection. The recognised + options are the following (they can be shortened to the lowest common + denominator): + + * __-keepalive__ + + is the number of seconds between each keepalive pings being sent along + the connection. A zero or negative number will effectively turn off the + feature. In servers, __-keepalive__ defaults to 30 seconds, and in + clients, no pings are initiated. + + * __-ping__ + + is the text that is used during the automated pings. This text defaults + to the empty string, leading to an empty ping. + + - __::websocket::loglevel__ ?*loglvl*? + + Set or query the log level of the library, which defaults to error. Logging + is built on top of the logger module, and the library makes use of the + following levels: __debug__, __info__, __notice__, __warn__ and __error__. + When called with no argument, this procedure will simply return the current + log level. Otherwise *loglvl* should contain the desired log level. + + - __::websocket::close__ *sock* ?*code*? ?*reason*? + + Gracefully close a websocket that was directly or indirectly passed to + __::websocket::takeover__. The procedure will optionally send the *code* and + describing *reason* as part of the closure handshake. Good defaults are + provided, so that reasons for a number of known codes will be sent back. + Only the first 125 characters of a reason string will be kept and sent as + part of the handshake. The known codes are: + + * __1000__ + + Normal closure (the default *code* when none provided). + + * __1001__ + + Endpoint going away + + * __1002__ + + Protocol Error + + * __1003__ + + Received incompatible data type + + * __1006__ + + Abnormal closure + + * __1007__ + + Received data not consistent with type + + * __1008__ + + Policy violation + + * __1009__ + + Received message too big + + * __1010__ + + Missing extension + + * __1011__ + + Unexpected condition + + * __1015__ + + TLS handshake error + +# Examples + +The following example opens a websocket connection to the echo service, waits +400ms to ensure that the connection is really established and sends a single +textual message which should be echoed back by the echo service. A real example +would probably use the __connect__ callback to know when connection to the +remote server has been establish and would only send data at that time. + + package require websocket + ::websocket::loglevel debug + + proc handler { sock type msg } { + switch -glob -nocase -- $type { + co* { + puts "Connected on $sock" + } + te* { + puts "RECEIVED: $msg" + } + cl* - + dis* { + } + } + + } + + proc test { sock } { + puts "[::websocket::conninfo $sock type] from [::websocket::conninfo $sock sockname] to [::websocket::conninfo $sock peername]" + + ::websocket::send $sock text "Testing, testing..." + } + + set sock [::websocket::open ws://echo.websocket.org/ handler] + after 400 test $sock + vwait forever + +# TLS Security Considerations + +This package uses the __[TLS](../../../../index.md#tls)__ package to handle the +security for __https__ urls and other socket connections. + +Policy decisions like the set of protocols to support and what ciphers to use +are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this +package itself however. Such decisions are the responsibility of whichever +application is using the package, and are likely influenced by the set of +servers the application will talk to as well. + +For example, in light of the recent [POODLE +attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html) +discovered by Google many servers will disable support for the SSLv3 protocol. +To handle this change the applications using __[TLS](../../../../index.md#tls)__ +must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__ +itself. Such a patch may be as simple as generally activating __tls1__ support, +as shown in the example below. + + package require tls + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol + + ... your own application code ... + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *websocket* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[http](../../../../index.md#http) + +# KEYWORDS + +[http](../../../../index.md#http), [internet](../../../../index.md#internet), +[net](../../../../index.md#net), [rfc 6455](../../../../index.md#rfc_6455) + +# CATEGORY + +Networking ADDED embedded/md/tcllib/files/modules/wip/wip.md Index: embedded/md/tcllib/files/modules/wip/wip.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/wip/wip.md @@ -0,0 +1,387 @@ + +[//000000001]: # (wip - Word Interpreter) +[//000000002]: # (Generated from file 'wip.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (wip(n) 2.2 tcllib "Word Interpreter") + +# NAME + +wip - Word Interpreter + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [GENERAL BEHAVIOUR](#section2) + + - [CLASS API](#section3) + + - [OBJECT API](#section4) + + - [EXAMPLES](#section5) + + - [Bugs, Ideas, Feedback](#section6) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require wip ?2.2? +package require snit ?1.3? +package require struct::set + +[__::wip__ *wipName* *engine* *arg*...](#1) +[__def__ *name*](#2) +[__def__ *name* *method_prefix*](#3) +[__wipName__ *option* ?*arg arg ...*?](#4) +[__wip::dsl__ ?*suffix*?](#5) +[*wipName* __def__ *name* ?*method_prefix*?](#6) +[*wipName* __defl__ *names*](#7) +[*wipName* __defd__ *dict*](#8) +[*wipName* __deflva__ *name*...](#9) +[*wipName* __defdva__ (*name* *method_prefix*)...](#10) +[*wipName* __undefl__ *names*](#11) +[*wipName* __undefva__ *name*...](#12) +[*wipName* __unknown__ *cmdprefix*](#13) +[*wipName* __runl__ *wordlist*](#14) +[*wipName* __run__ *word*...](#15) +[*wipName* __run_next__](#16) +[*wipName* __run_next_while__ *acceptable*](#17) +[*wipName* __run_next_until__ *rejected*](#18) +[*wipName* __run_next_if__ *acceptable*](#19) +[*wipName* __run_next_ifnot__ *rejected*](#20) +[*wipName* __next__](#21) +[*wipName* __peek__](#22) +[*wipName* __peekall__](#23) +[*wipName* __insertl__ *at* *wordlist*](#24) +[*wipName* __replacel__ *wordlist*](#25) +[*wipName* __pushl__ *wordlist*](#26) +[*wipName* __addl__ *wordlist*](#27) +[*wipName* __insert__ *at* *word*...](#28) +[*wipName* __replace__ *word*...](#29) +[*wipName* __push__ *word*...](#30) +[*wipName* __add__ *word*...](#31) + +# DESCRIPTION + +This package provides a micro interpreter for lists of words. Domain specific +languages based on this will have a bit of a Forth feel, with the input stream +segmented into words and any other structuring left to whatever the language +desired. Note that we have here in essence only the core dispatch loop, and no +actual commands whatsoever, making this definitely only a Forth feel and not an +actual Forth. + +The idea is derived from Colin McCormack's __[treeql](../treeql/treeql.md)__ +processor, modified to require less boiler plate within the command +implementations, at the expense of, likely, execution speed. In addition the +interface between processor core and commands is more complex too. + +# GENERAL BEHAVIOUR + +Word interpreters have a mappping from the names of the language commands they +shall recognize to the methods in the engine to invoke for them, and possibly +fixed arguments for these methods. This mapping is largely static, however it is +possible to change it during the execution of a word list (= program). + +At the time a language command is defined the word interpreter will use +__[snit](../snit/snit.md)__'s introspection capabilities to determine the number +of arguments expected by the method of the egnine, and together with the number +of fixed arguments supplied in the method prefix of the mapping it then knows +how many arguments the language command is expecting. This is the command's +*arity*. Variable-argument methods (i.e. with the last argument named *args*) +are *not* allowed and will cause the word interpreter to throw an error at +definition time. + +Note that while I said __[snit](../snit/snit.md)__'s abilities the engine object +can be written in any way, as long as it understands the method __info args__, +which takes a method name and returns the list of arguments for that method. + +When executing a list of words (aka program) the first word is always taken as +the name of a language command, and the next words as its arguments, per the +*arity* of the command. Command and argument words are removed from the list and +then associated method of the engine is executed with the argument words. The +process then repeats using the then-first word of the list. + +Note that the methods implementing the language commands may have full access to +the list of words and are allowed to manipulate as they see fit. + + 1. This means, for example, that while we cannot specify variable-argument + methods directly they can consume words after their fixed arguments before + returning to the execution loop. This may be under the control of their + fixed arguments. + + 1. Another possibility is the use of method __run_next__ and its variants to + execute commands coming after the current command, changing the order of + execution. + + 1. Execution can be further changed by use of the program accessor methods + which allow a command implementation to modify the remaining list of words + (insert, replace, prepend, append words) without executing them + immediately. + + 1. At last the basic __run__ methods save and restore an existing list of + words when used, enabling recursive use from within command + implementations. + +# CLASS API + +The main command of the package is: + + - __::wip__ *wipName* *engine* *arg*... + + The command creates a new word interpreter object with an associated global + Tcl command whose name is *wipName*. If however the string __%AUTO%__ was + used as object name the package will generate its own unique name for the + object. + + The *engine* is the object the word interpreter will dispatch all recognized + commands to, and the *arg*uments are a word list which defines an initial + mapping from language words to engine methods. + + The recognized language of this word list is + + * __def__ *name* + + Defines *name* as command of the language, to be mapped to a method of + the *engine* having the same name. + + * __def__ *name* *method_prefix* + + Defines *name* as command of the language, to be mapped to the method of + the *engine* named in the *method_prefix*. + + The returned command may be used to invoke various operations on the object. + It has the following general form: + + * __wipName__ *option* ?*arg arg ...*? + + *Option* and the *arg*s determine the exact behavior of the command. + +The package additionally exports the command: + + - __wip::dsl__ ?*suffix*? + + This command is for use within snit types which wish to use one or more wip + interpreters as a component. Use within the type definition installs most of + the boilerplate needed to setup and use a word interpreter. + + It installs a component named *wip*, and a method __wip_setup__ for + initializing it. This method has to be called from within the constructor of + the type using the word interpreter. If further installs a series of + procedures which make the object API of the word interpreter directly + available to the type's methods, without having to specify the component. + + *Note* that this does and cannot install the language to interpret, i.e. the + mapping from words to engine methods. + + It is possible to instantiate multiple word interpreter components within a + type by using different suffices as arguments to the command. In that case + the name of the component changes to 'wip___$suffix__', the setup command + becomes 'wip___$suffix___setup' and all the procedures also get the suffix + '___$suffix__'. + +# OBJECT API + +The following commands are possible for word interpreter objects: + + - *wipName* __def__ *name* ?*method_prefix*? + + Defines a language command *name* and maps it to the method named in the + engine's *method_prefix*. If the *method_prefix* name is not specified it is + simply the name of the language command. + + - *wipName* __defl__ *names* + + Defines a series of language commands, specified through the list of + *names*, all of which are mapped to engine methods of the same name. + + - *wipName* __defd__ *dict* + + Defines a series of language commands, specified through the dictionary + *dict* of names and method prefixes. + + - *wipName* __deflva__ *name*... + + As method __defl__, however the list of names is specified through multiple + arguments. + + - *wipName* __defdva__ (*name* *method_prefix*)... + + As method __defd__, however the dictionary of names and method prefixes is + specified through multiple arguments. + + - *wipName* __undefl__ *names* + + Removes the named series of language commands from the mapping. + + - *wipName* __undefva__ *name*... + + As method __undefl__, however the list of names is specified through + multiple arguments. + + - *wipName* __unknown__ *cmdprefix* + + Sets the handler for unknown words to *cmdprefix*. This command prefix takes + one argument, the current word, and either throws some error, or returns the + result of executing the word, as defined by the handler. The default handler + simply throws an error. + + - *wipName* __runl__ *wordlist* + + Treats the list of words in *wordlist* as a program and executes the + contained command one by one. The result of the command executed last is + returned as the result of this command. + + The *wordlist* is stored in the object for access by the other + *run*-methods, and the general program accessor methods (see below). A + previously stored wordlist is saved during the execution of this method and + restored before it returns. This enables the recursive execution of word + lists within word lists. + + - *wipName* __run__ *word*... + + As method __runl__, however the list of words to execute is specified + through multiple arguments. + + - *wipName* __run_next__ + + Low-level method. Determines the next word in the list of words, and its + arguments, and then executes it. The result of the executed word is the + result of this method. + + Exposed for use within command implementations. The methods __run__ and + __runl__ use it to execute words until their word list is exhausted. + + - *wipName* __run_next_while__ *acceptable* + + Low-level method. Invokes the method __run_next__ as long as the next word + is in the set of *acceptable* words, and the program is not empty. The + result of the command executed last is returned as the result of this + command. + + Exposed for use within command implementations to change the order of + execution. + + - *wipName* __run_next_until__ *rejected* + + Low-level method. Invokes the method __run_next__ until the next word is in + the set of *rejected* words, and the program is not empty. The result of the + command executed last is returned as the result of this command. + + Exposed for use within command implementations to change the order of + execution. + + - *wipName* __run_next_if__ *acceptable* + + Low-level method. Invokes the method __run_next__ if the next word is in the + set of *acceptable* words, and the program is not empty. The result of the + command executed last is returned as the result of this command. + + Exposed for use within command implementations to change the order of + execution. + + - *wipName* __run_next_ifnot__ *rejected* + + Low-level method. Invokes the method __run_next__ if the next word is not in + the set of *rejected* words, and the program is not empty. The result of the + command executed last is returned as the result of this command. + + Exposed for use within command implementations to change the order of + execution. + + - *wipName* __next__ + + Returns the next word in the programm. The word is also removed. + + - *wipName* __peek__ + + Returns the next word in the programm without removing it + + - *wipName* __peekall__ + + Returns the remaining programm in toto. + + - *wipName* __insertl__ *at* *wordlist* + + Basic programm accessor method. Inserts the specified *wordlist* into the + program, just before the word at position *at*. Positions are counted from + __zero__. + + - *wipName* __replacel__ *wordlist* + + Basic programm accessor method. Replaces the whole stored program with the + specified *wordlist*. + + - *wipName* __pushl__ *wordlist* + + Program accessor method. The specified *wordlist* is added to the front of + the remaining program. Equivalent to + + $wip insertl 0 $wordlist + + - *wipName* __addl__ *wordlist* + + Program accessor method. The specified *wordlist* is appended at the end of + the remaining program. Equivalent to + + $wip insertl end $wordlist + + - *wipName* __insert__ *at* *word*... + + Like method __insertl__, except the words are specified through multiple + arguments. + + - *wipName* __replace__ *word*... + + Like method __setl__, except the words are specified through multiple + arguments. + + - *wipName* __push__ *word*... + + Like method __pushl__, except the words are specified through multiple + arguments. + + - *wipName* __add__ *word*... + + Like method __addl__, except the words are specified through multiple + arguments. + +# EXAMPLES + +No examples yet. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *wip* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[interpreter](../../../../index.md#interpreter), +[list](../../../../index.md#list), [word](../../../../index.md#word) + +# CATEGORY + +Programming tools + +# COPYRIGHT + +Copyright © 2007-2010 Andreas Kupries ADDED embedded/md/tcllib/files/modules/yaml/huddle.md Index: embedded/md/tcllib/files/modules/yaml/huddle.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/yaml/huddle.md @@ -0,0 +1,631 @@ + +[//000000001]: # (huddle - HUDDLE) +[//000000002]: # (Generated from file 'huddle.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (huddle(n) 0.3 tcllib "HUDDLE") + +# NAME + +huddle - Create and manipulate huddle object + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [TYPE CALLBACK](#section3) + + - [How to add type](#section4) + + - [WORKING SAMPLE](#section5) + + - [LIMITATIONS](#section6) + + - [Bugs, Ideas, Feedback](#section7) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require huddle ?0.3? + +[__huddle create__ *key* *value* ?*key value ...*?](#1) +[__huddle list__ ?*value value ...*?](#2) +[__huddle number__ *number*](#3) +[__huddle string__ *string*](#4) +[__huddle boolean__ *expression to evaluate as true or false*](#5) +[__huddle true__](#6) +[__huddle false__](#7) +[__huddle null__](#8) +[__huddle get__ *object* *key* ?*key ...*?](#9) +[__huddle gets__ *object* *key* ?*key ...*?](#10) +[__huddle set__ *objectVar* *key* ?*key ...*? *value*](#11) +[__huddle remove__ *object* *key* ?*key ...*?](#12) +[__huddle combine__ *object1* *object2* ?*object3 ...*?](#13) +[__huddle equal__ *object1* *object2*](#14) +[__huddle append__ *objectVar* *key* *value* ?*key value ...*?](#15) +[__huddle append__ *objectVar* *value* ?*value ...*?](#16) +[__huddle keys__ *object*](#17) +[__huddle llength__ *object*](#18) +[__huddle type__ *object* ?*key key...*?](#19) +[__huddle strip__ *object*](#20) +[__huddle jsondump__ *object* ?*offset*? ?*newline*? ?*begin_offset*?](#21) +[__huddle compile__ *spec* *data*](#22) +[__huddle isHuddle__ *object*](#23) +[__huddle checkHuddle__ *object*](#24) +[__huddle to_node__ *object* ?*tag*?](#25) +[__huddle wrap__ *tag* *src*](#26) +[__huddle call__ *tag* *command* *args*](#27) +[__huddle addType__ *callback*](#28) +[__[callback](../../../../index.md#callback)__ *command* ?*args*?](#29) +[__setting__](#30) +[__get_sub__ *src* *key*](#31) +[__strip__ *src*](#32) +[__[set](../../../../index.md#set)__ *src* *key* *value*](#33) +[__[remove](../../../../index.md#remove)__ *src* *key* *value*](#34) + +# DESCRIPTION + +Huddle provides a generic Tcl-based serialization/intermediary format. +Currently, each node is wrapped in a tag with simple type information. + +When converting huddle-notation to other serialization formats like JSON or YAML +this type information is used to select the proper notation. And when going from +JSON/YAML/... to huddle their notation can be used to select the proper huddle +type. + +In that manner huddle can serve as a common intermediary format. + + huddle-format: > + {HUDDLE {huddle-node}} + huddle-node: > + {tag content} + each content of tag means: + s: (content is a) string + L: list, each sub node is a huddle-node + D: dict, each sub node is a huddle-node + confirmed: + - JSON + - YAML(generally, but cannot discribe YAML-tags) + limitation: + - cannot discribe aliases from a node to other node. + +The __huddle__ package returns data as a Tcl +__[dict](../../../../index.md#dict)__. Either the +__[dict](../../../../index.md#dict)__ package or Tcl 8.5 is required for use. + +# COMMANDS + + - __huddle create__ *key* *value* ?*key value ...*? + + Create a huddle object as a dict. It can contain other huddle objects. + + - __huddle list__ ?*value value ...*? + + Create a huddle object as a list. It can contain other huddle objects. + + - __huddle number__ *number* + + Create a huddle object as a number. + + - __huddle string__ *string* + + Create a huddle object as a string. + + - __huddle boolean__ *expression to evaluate as true or false* + + Create a huddle object as a boolean evaluating an expression as true or + false- + + - __huddle true__ + + Create a huddle object as a boolean true. + + - __huddle false__ + + Create a huddle object as a boolean false. + + - __huddle null__ + + Create a huddle object as a null. + + - __huddle get__ *object* *key* ?*key ...*? + + Almost the same as __dict get__. Get a sub-object from the huddle object. + *key* can be used to huddle-list's index. + + - __huddle gets__ *object* *key* ?*key ...*? + + Get a sub-object from the huddle object, stripped. + + - __huddle set__ *objectVar* *key* ?*key ...*? *value* + + Almost the same as __dict set__. Set a sub-object from the huddle object. + *key* can be used to huddle-list's index. + + - __huddle remove__ *object* *key* ?*key ...*? + + Almost the same as __dict remove__. Remove a sub-object from the huddle + object. *key* can be used to huddle-list's index. + + - __huddle combine__ *object1* *object2* ?*object3 ...*? + + Merging huddle objects given. + + % set aa [huddle create a b c d] + HUDDLE {D {a {s b} c {s d}}} + % set bb [huddle create a k l m] + HUDDLE {D {a {s k} l {s m}}} + % huddle combine $aa $bb + HUDDLE {D {a {s k} c {s d} l {s m}}} + + - __huddle equal__ *object1* *object2* + + Comparing two huddle objects recursively. When to equal, returns 1, + otherwise 0. + + % set aa [huddle create a b c d] + HUDDLE {D {a {s b} c {s d}}} + % set bb [huddle create c d a b] + HUDDLE {D {c {s d} a {s b}}} + % huddle equal $aa $bb + 1 + + - __huddle append__ *objectVar* *key* *value* ?*key value ...*? + + - __huddle append__ *objectVar* *value* ?*value ...*? + + Appending child elements. When for dicts, giving key/value. When for lists, + giving values. + + % set aa [huddle create a b c d] + HUDDLE {D {a {s b} c {s d}}} + % huddle append aa a k l m + HUDDLE {D {a {s k} c {s d} l {s m}}} + % set bb [huddle list i j k l] + HUDDLE {L {{s i} {s j} {s k} {s l}}} + % huddle append bb g h i + HUDDLE {L {{s i} {s j} {s k} {s l} {s g} {s h} {s i}}} + + - __huddle keys__ *object* + + The same as __dict keys__. + + - __huddle llength__ *object* + + The same as __llength__. + + - __huddle type__ *object* ?*key key...*? + + Return the element type of specified by keys. if ?key? is not given, returns + the type of root node. + + * ____string____ + + the node is a tcl's string. + + * ____dict____ + + the node is a dict. + + * ____list____ + + the node is a list. + + * ____number____ + + the node is a number. + + * ____boolean____ + + the node is a boolean. + + * ____null____ + + the node is a null. + + % huddle type {HUDDLE {s str}} + string + % huddle type {HUDDLE {L {{s a} {s b} {s c}}}} + list + % huddle type {HUDDLE {D {aa {s b} cc {s d}}}} cc + string + + - __huddle strip__ *object* + + Stripped all tags. Converted to normal Tcl's list/dict. + + - __huddle jsondump__ *object* ?*offset*? ?*newline*? ?*begin_offset*? + + dump a json-stream from the huddle-object. + + * ____offset__ ""__ + + begin offset as spaces " ". + + # normal output has some indents. some strings are escaped. + % huddle jsondump {HUDDLE {L {{L {{s i} {s baa} {s \\k} {L {{s 1.0} {s true} {s /g} {s h}}} {L {{s g}}}}} {s t}}}} + [ + [ + "i", + "baa", + "\\k", + [ + 1.0, + true, + "\/g", + "h" + ], + ["g"] + ], + "t" + ] + # stripped output + % huddle jsondump {HUDDLE {D {dd {D {bb {D {a {s baa} c {s {d + a}}}} cc {D {g {s h}}}}} ee {D {i {s j} k {s 1} j {s { m\a}}}}}}} "" "" + {"dd": {"bb": {"a": "baa","c": "d\na"},"cc": {"g": "h"}},"ee": {"i": "j","k": 1,"j": " m\\a"}} + + - __huddle compile__ *spec* *data* + + construct a huddle object from plain old tcl values. *spec* is defined as + follows: + + * __string__ + + data is simply a string + + * __list__ + + data is a tcl list of strings + + * __dict__ + + data is a tcl dict of strings + + * list list + + data is a tcl list of lists + + * list dict + + data is a tcl list of dicts + + * dict xx list + + data is a tcl dict where the value of key xx is a tcl list + + * dict * list + + data is a tcl dict of lists *data* is plain old tcl values + + % huddle compile {dict * list} {a {1 2 3} b {4 5}} + HUDDLE {D {a {L {{s 1} {s 2} {s 3}}} b {L {{s 4} {s 5}}}}} + % huddle compile {dict * {list {dict d list}}} {a {{c 1} {d {2 2 2} e 3}} b {{f 4 g 5}}} + HUDDLE {D {a {L {{D {c {s 1}}} {D {d {L {{s 2} {s 2} {s 2}}} e {s 3}}}}} b {L {{D {f {s 4} g {s 5}}}}}}} + + - __huddle isHuddle__ *object* + + if *object* is a huddle, returns 1. the other, returns 0. + + - __huddle checkHuddle__ *object* + + if *object* is not a huddle, rises an error. + + - __huddle to_node__ *object* ?*tag*? + + for type-callbacks. + + if *object* is a huddle, returns root-node. the other, returns __[list s + $object]__. + + % huddle to_node str + s str + % huddle to_node str !!str + !!str str + % huddle to_node {HUDDLE {s str}} + s str + % huddle to_node {HUDDLE {l {a b c}}} + l {a b c} + + - __huddle wrap__ *tag* *src* + + for type-callbacks. + + Create a huddle object from *src* with specified *tag*. + + % huddle wrap "" str + HUDDLE str + % huddle wrap s str + HUDDLE {s str} + + - __huddle call__ *tag* *command* *args* + + for type-callbacks. + + devolving *command* to default *tag*-callback + + - __huddle addType__ *callback* + + add a user-specified-type/tag to the huddle library. To see "Additional + Type". + + * __callback__ + + callback function name for additional type. + +# TYPE CALLBACK + +The definition of callback for user-type. + + - __[callback](../../../../index.md#callback)__ *command* ?*args*? + + * __command__ + + huddle subcomand which is needed to reply by the callback. + + * __args__ + + arguments of subcommand. The number of list of arguments is different + for each subcommand. + +The callback procedure shuould reply the following subcommands. + + - __setting__ + + only returns a fixed dict of the type infomation for setting the user-tag. + + * __type__ typename + + typename of the type + + * __method__ {method1 method2 method3 ...} + + method list as huddle subcommand. Then, you can call __[huddle method1 + ...]__ + + * __tag__ {tag1 child/parent tag2 child/parent ...} + + tag list for huddle-node as a dict. if the type has child-nodes, use + "parent", otherwise use "child". + + - __get_sub__ *src* *key* + + returns a sub node specified by *key*. + + * __src__ + + a node content in huddle object. + + - __strip__ *src* + + returns stripped node contents. if the type has child nodes, every node must + be stripped. + + - __[set](../../../../index.md#set)__ *src* *key* *value* + + sets a sub-node from the tagged-content, and returns self. + + - __[remove](../../../../index.md#remove)__ *src* *key* *value* + + removes a sub-node from the tagged-content, and returns self. + +__strip__ must be defined at all types. __get_sub__ must be defined at container +types. __set/remove__ shuould be defined, if you call them. + + # callback sample for my-dict + proc my_dict_setting {command args} { + switch -- $command { + setting { ; # type definition + return { + type dict + method {create keys} + tag {d child D parent} + constructor create + str s + } + # type: the type-name + # method: add methods to huddle's subcommand. + # "get_sub/strip/set/remove/equal/append" called by huddle module. + # "strip" must be defined at all types. + # "get_sub" must be defined at container types. + # "set/remove/equal/append" shuould be defined, if you call them. + # tag: tag definition("child/parent" word is maybe obsoleted) + } + get_sub { ; # get a sub-node specified by "key" from the tagged-content + foreach {src key} $args break + return [dict get $src $key] + } + strip { ; # strip from the tagged-content + foreach {src nop} $args break + foreach {key val} $src { + lappend result $key [huddle strip $val] + } + return $result + } + set { ; # set a sub-node from the tagged-content + foreach {src key value} $args break + dict set src $key $value + return $src + } + remove { ; # remove a sub-node from the tagged-content + foreach {src key value} $args break + return [dict remove $src $key] + } + equal { ; # check equal for each node + foreach {src1 src2} $args break + if {[llength $src1] != [llength $src2]} {return 0} + foreach {key1 val1} $src1 { + if {![dict exists $src2 $key1]} {return 0} + if {![huddle _equal_subs $val1 [dict get $src2 $key1]]} {return 0} + } + return 1 + } + append { ; # append nodes + foreach {str src list} $args break + if {[llength $list] % 2} {error {wrong # args: should be "huddle append objvar ?key value ...?"}} + set resultL $src + foreach {key value} $list { + if {$str ne ""} { + lappend resultL $key [huddle to_node $value $str] + } else { + lappend resultL $key $value + } + } + return [eval dict create $resultL] + } + create { ; # $args: all arguments after "huddle create" + if {[llength $args] % 2} {error {wrong # args: should be "huddle create ?key value ...?"}} + set resultL {} + foreach {key value} $args { + lappend resultL $key [huddle to_node $value] + } + return [huddle wrap D $resultL] + } + keys { + foreach {src nop} $args break + return [dict keys [lindex [lindex $src 1] 1]] + } + default { + error "$command is not callback for dict" + } + } + } + + # inheritance sample from default dict-callback + proc ::yaml::_huddle_mapping {command args} { + switch -- $command { + setting { ; # type definition + return { + type dict + method {mapping} + tag {!!map parent} + constructor mapping + str !!str + } + } + mapping { ; # $args: all arguments after "huddle mapping" + if {[llength $args] % 2} {error {wrong # args: should be "huddle mapping ?key value ...?"}} + set resultL {} + foreach {key value} $args { + lappend resultL $key [huddle to_node $value !!str] + } + return [huddle wrap !!map $resultL] + } + default { ; # devolving to default dict-callback + return [huddle call D $command $args] + } + } + } + +# How to add type + +You can add huddle-node types e.g. ::struct::tree. To do so, first, define a +callback-procedure for additional tagged-type. The proc get argments as +*command* and ?*args*?. It has some switch-sections. + +And, addType subcommand will called. + + huddle addType my_dict_setting + +# WORKING SAMPLE + + # create as a dict + % set bb [huddle create a b c d] + HUDDLE {D {a {s b} c {s d}}} + + # create as a list + % set cc [huddle list e f g h] + HUDDLE {L {{s e} {s f} {s g} {s h}}} + % set bbcc [huddle create bb $bb cc $cc] + HUDDLE {D {bb {D {a {s b} c {s d}}} cc {L {{s e} {s f} {s g} {s h}}}}} + % set folding [huddle list $bbcc p [huddle list q r] s] + HUDDLE {L {{D {bb {D {a {s b} c {s d}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q} {s r}}} {s s}}} + + # normal Tcl's notation + % huddle strip $folding + {bb {a b c d} cc {e f g h}} p {q r} s + + # get a sub node + % huddle get $folding 0 bb + HUDDLE {D {a {s b} c {s d}}} + % huddle gets $folding 0 bb + a b c d + + # overwrite a node + % huddle set folding 0 bb c kkk + HUDDLE {L {{D {bb {D {a {s b} c {s kkk}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q} {s r}}} {s s}}} + + # remove a node + % huddle remove $folding 2 1 + HUDDLE {L {{D {bb {D {a {s b} c {s kkk}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q}}} {s s}}} + % huddle strip $folding + {bb {a b c kkk} cc {e f g h}} p {q r} s + + # dump as a JSON stream + % huddle jsondump $folding + [ + { + "bb": { + "a": "b", + "c": "kkk" + }, + "cc": [ + "e", + "f", + "g", + "h" + ] + }, + "p", + [ + "q", + "r" + ], + "s" + ] + +# LIMITATIONS + +now printing. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *huddle* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[yaml](yaml.md) + +# KEYWORDS + +[data exchange](../../../../index.md#data_exchange), [exchange +format](../../../../index.md#exchange_format), +[huddle](../../../../index.md#huddle), [json](../../../../index.md#json), +[parsing](../../../../index.md#parsing), [text +processing](../../../../index.md#text_processing), +[yaml](../../../../index.md#yaml) + +# COPYRIGHT + +Copyright © 2008-2011 KATO Kanryu +Copyright © 2015 Miguel Martínez López ADDED embedded/md/tcllib/files/modules/yaml/yaml.md Index: embedded/md/tcllib/files/modules/yaml/yaml.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/yaml/yaml.md @@ -0,0 +1,230 @@ + +[//000000001]: # (yaml - YAML processing) +[//000000002]: # (Generated from file 'yaml.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (yaml(n) 0.4.1 tcllib "YAML processing") + +# NAME + +yaml - YAML Format Encoder/Decoder + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [COMMANDS](#section2) + + - [EXAMPLES](#section3) + + - [LIMITATIONS](#section4) + + - [Bugs, Ideas, Feedback](#section5) + + - [See Also](#see-also) + + - [Keywords](#keywords) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require yaml ?0.4.1? + +[__::yaml::yaml2dict__ ?*options*? *txt*](#1) +[__::yaml::yaml2huddle__ ?*options*? *txt*](#2) +[__::yaml::setOption__ ?*options*?](#3) +[__::yaml::dict2yaml__ *dict* ?*indent*? ?*wordwrap*?](#4) +[__::yaml::list2yaml__ *list* ?*indent*? ?*wordwrap*?](#5) +[__::yaml::huddle2yaml__ *huddle* ?*indent*? ?*wordwrap*?](#6) + +# DESCRIPTION + +The __yaml__ package provides a simple Tcl-only library for parsing the YAML +[http://www.yaml.org/](http://www.yaml.org/) data exchange format as specified +in [http://www.yaml.org/spec/1.1/](http://www.yaml.org/spec/1.1/). + +The __yaml__ package returns data as a Tcl +__[dict](../../../../index.md#dict)__. Either the +__[dict](../../../../index.md#dict)__ package or Tcl 8.5 is required for use. + +# COMMANDS + + - __::yaml::yaml2dict__ ?*options*? *txt* + + - __::yaml::yaml2huddle__ ?*options*? *txt* + + Parse yaml formatted text *txt* into a Tcl dict/huddle and return the value. + + * ____-file____ + + *txt* is a filename of YAML-stream. + + * ____-stream____ + + *txt* is just a YAML-stream. + + * ____-types__ *list*__ + + The *list* is a type list for the yaml-scalar types.(e.g. !!str + !!timestamp !!integer !!true ...) + + -types {timestamp integer null true false} + + In this case, if a string matched "timestamp", converted to the TCL + internal timestamp.(e.g. "2001-12-15T02:59:43.1Z" => 1008385183) + + * ____-m:true__ *param*__ + + The *param* is two elements of list for the value of true, and + considered strings. + + -m:true {1 {true on + yes y}} + + In this case, the string "yes" found in YAML Stream, automatically + converted 1. + + * ____-m:false__ *param*__ + + The *param* is two elements of list for the value of false, and + considered strings. + + -m:false {0 {false off - no n}} + + * ____-m:null__ *param*__ + + The *param* is two elements of list for the value of null, and + considered strings. + + -m:null {"" {null nil "" ~}} + + * ____-validate____ + + Experiment,old: Output stream contains YAML's-tag, each node. + + % puts [::yaml::load -validate {[aaa, bbb]}] + => + !!seq {{!!str aaa} {!!str bbb}} + + - __::yaml::setOption__ ?*options*? + + Change implicit options for the library. Now, the params are the same as + __::yaml::yaml2dict__. Arguments of__::yaml::yaml2dict__ is more priority + than this setting. + + - __::yaml::dict2yaml__ *dict* ?*indent*? ?*wordwrap*? + + - __::yaml::list2yaml__ *list* ?*indent*? ?*wordwrap*? + + - __::yaml::huddle2yaml__ *huddle* ?*indent*? ?*wordwrap*? + + Convert a dict/list/huddle object into YAML stream. + + * indent + + spaces indent of each block node. currently default is 2. + + * wordwrap + + word wrap for YAML stream. currently default is 40. + +# EXAMPLES + +An example of a yaml stream converted to Tcl. A yaml stream is returned as a +single item with multiple elements. + + { + --- ! + invoice: 34843 + date : 2001-01-23 + bill-to: &id001 + given : Chris + family : Dumars + address: + lines: | + 458 Walkman Dr. + Suite #292 + city : Royal Oak + state : MI + postal : 48046 + ship-to: *id001 + product: + - sku : BL394D + quantity : 4 + description : Basketball + price : 450.00 + - sku : BL4438H + quantity : 1 + description : Super Hoop + price : 2392.00 + tax : 251.42 + total: 4443.52 + comments: + Late afternoon is best. + Backup contact is Nancy + Billsmer @ 338-4338. + } + => + invoice 34843 date 2001-01-23 bill-to {given Chris family Dumars address {lines {458 Walkman Dr. + Suite #292 + } city {Royal Oak} state MI postal 48046}} ship-to {given Chris family Dumars address {lines {458 Walkman Dr. + Suite #292 + } city {Royal Oak} state MI postal 48046}} product {{sku BL394D quantity 4 description Basketball price 450.00} {sku BL4438H quantity 1 description {Super Hoop} price 2392.00}} tax 251.42 total 4443.52 comments {Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.} + +An example of a yaml object converted to Tcl. A yaml object is returned as a +multi-element list (a dict). + + { + --- + - [name , hr, avg ] + - [Mark McGwire, 65, 0.278] + - [Sammy Sosa , 63, 0.288] + - + Mark McGwire: {hr: 65, avg: 0.278} + Sammy Sosa: { hr: 63, avg: 0.288} + } + => + {name hr avg} {{Mark McGwire} 65 0.278} {{Sammy Sosa} 63 0.288} {{Mark McGwire} {hr 65 avg 0.278} {Sammy Sosa} {hr 63 avg 0.288}} + +# LIMITATIONS + +tag parser not implemented. currentry, tags are merely ignored. + +Only Anchor => Aliases ordering. back alias-referring is not supported. + +Too many braces, or too few braces. + +Not enough character set of line feeds. Please use only "\n" as line breaks. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *yaml* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# SEE ALSO + +[base64](../base64/base64.md), [huddle](huddle.md), [json](../json/json.md) + +# KEYWORDS + +[data exchange](../../../../index.md#data_exchange), +[huddle](../../../../index.md#huddle), [parsing](../../../../index.md#parsing), +[text processing](../../../../index.md#text_processing), +[yaml](../../../../index.md#yaml) + +# COPYRIGHT + +Copyright © 2008 KATO Kanryu ADDED embedded/md/tcllib/files/modules/zip/decode.md Index: embedded/md/tcllib/files/modules/zip/decode.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/zip/decode.md @@ -0,0 +1,161 @@ + +[//000000001]: # (zipfile::decode - Zip archive handling) +[//000000002]: # (Generated from file 'decode.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (zipfile::decode(n) 0.7.1 tcllib "Zip archive handling") + +# NAME + +zipfile::decode - Access to zip archives + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require fileutil::magic::mimetype +package require fileutil::decode 0.2.1 +package require Trf +package require zlibtcl +package require zipfile::decode ?0.7.1? + +[__::zipfile::decode::archive__](#1) +[__::zipfile::decode::close__](#2) +[__::zipfile::decode::comment__ *adict*](#3) +[__::zipfile::decode::content__ *archive*](#4) +[__::zipfile::decode::copyfile__ *adict* *path* *dst*](#5) +[__::zipfile::decode::files__ *adict*](#6) +[__::zipfile::decode::getfile__ *zdict* *path*](#7) +[__::zipfile::decode::hasfile__ *adict* *path*](#8) +[__::zipfile::decode::iszip__ *archive*](#9) +[__::zipfile::decode::open__ *archive*](#10) +[__::zipfile::decode::unzip__ *adict* *dstdir*](#11) +[__::zipfile::decode::unzipfile__ *archive* *dstdir*](#12) + +# DESCRIPTION + +This package provides commands to decompress and access the contents of zip +archives. + +# API + + - __::zipfile::decode::archive__ + + This command decodes the last opened (and not yet closed) zip archive file. + The result of the command is a dictionary describing the contents of the + archive. The structure of this dictionary is not public. Proper access + should be made through the provided accessor command of this package. + + - __::zipfile::decode::close__ + + This command releases all state associated with the last call of + __::zipfile::decode::open__. The result of the command is the empty string. + + - __::zipfile::decode::comment__ *adict* + + This command takes a dictionary describing the currently open zip archive + file, as returned by __::zipfile::decode::archive__, and returns the global + comment of the archive. + + - __::zipfile::decode::content__ *archive* + + This is a convenience command which decodes the specified zip *archive* file + and returns the list of paths found in it as its result. + + - __::zipfile::decode::copyfile__ *adict* *path* *dst* + + This command takes a dictionary describing the currently open zip archive + file, as returned by __::zipfile::decode::archive__, and copies the + decompressed contents of the file *path* in the archive to the the file + *dst*. An error is thrown if the file is not found in the archive. + + - __::zipfile::decode::files__ *adict* + + This command takes a dictionary describing the currently open zip archive + file, as returned by __::zipfile::decode::archive__, and returns the list of + files found in the archive. + + - __::zipfile::decode::getfile__ *zdict* *path* + + This command takes a dictionary describing the currently open zip archive + file, as returned by __::zipfile::decode::archive__, and returns the + decompressed contents of the file *path* in the archive. An error is thrown + if the file is not found in the archive. + + - __::zipfile::decode::hasfile__ *adict* *path* + + This command takes a dictionary describing the currently open zip archive + file, as returned by __::zipfile::decode::archive__, and check if the + specified *path* is found in the archive. The result of the command is a + boolean flag, __true__ if the path is found, and __false__ otherwise. + + - __::zipfile::decode::iszip__ *archive* + + This command takes the path of a presumed zip *archive* file and returns a + boolean flag as the result of the command telling us if it actually is a zip + archive (__true__), or not (__false__). + + - __::zipfile::decode::open__ *archive* + + This command takes the path of a zip *archive* file and prepares it for + decoding. The result of the command is the empty string. All important + information is stored in global state. If multiple open calls are made one + after the other only the state of the last call is available to the other + commands. + + - __::zipfile::decode::unzip__ *adict* *dstdir* + + This command takes a dictionary describing the currently open zip archive + file, as returned by __::zipfile::decode::archive__, and unpacks the archive + in the given destination directory *dstdir*. The result of the command is + the empty string. + + - __::zipfile::decode::unzipfile__ *archive* *dstdir* + + This is a convenience command which unpacks the specified zip *archive* file + in the given destination directory *dstdir*. + + The result of the command is the empty string. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *zipfile* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[decompression](../../../../index.md#decompression), +[zip](../../../../index.md#zip) + +# CATEGORY + +File + +# COPYRIGHT + +Copyright © 2008-2016 Andreas Kupries ADDED embedded/md/tcllib/files/modules/zip/encode.md Index: embedded/md/tcllib/files/modules/zip/encode.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/zip/encode.md @@ -0,0 +1,117 @@ + +[//000000001]: # (zipfile::encode - Zip archive handling) +[//000000002]: # (Generated from file 'encode.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (zipfile::encode(n) 0.4 tcllib "Zip archive handling") + +# NAME + +zipfile::encode - Generation of zip archives + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Class API](#section2) + + - [Instance API](#section3) + + - [Bugs, Ideas, Feedback](#section4) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.4 +package require logger +package require Trf +package require crc32 +package require snit +package require zlibtcl +package require fileutil +package require zipfile::encode ?0.4? + +[__::zipfile::encode__ ?*objectName*?](#1) +[____ __comment:__ *text*](#2) +[____ __file:__ *dst* *owned* *src* ?*noCompress*?](#3) +[____ __write__ *archive*](#4) + +# DESCRIPTION + +This package provides a class for the generation of zip archives. + +# Class API + + - __::zipfile::encode__ ?*objectName*? + + The class command constructs encoder instances, i.e. objects. The result of + the command is the fully-qualified name of the instance command. + + If no *objectName* is specified the class will generate and use an automatic + name. If the *objectName* was specified, but is not fully qualified the + command will be created in the current namespace. + +# Instance API + + - ____ __comment:__ *text* + + This method specifies the text of the global comment for the archive. The + result of the method is the empty string. In case of multiple calls to this + method for the same encoder the data from the last call prevails over all + previous texts. + + - ____ __file:__ *dst* *owned* *src* ?*noCompress*? + + This method adds a new file to the archive. The contents of the file are + found in the filesystem at *src*, and will be stored in the archive under + path *dst*. If the file is declared as *owned* by the archive the original + file will be deleted when the archive is constructed and written. If + *noCompress* is set to __true__ the file will not be compressed on writing. + Otherwise (the default) the file is compressed if it is advantageous. The + result of the method is an empty string. + + - ____ __write__ *archive* + + This method takes the global comment and all added files, encodes them as a + zip archive and stores the result at path *archive* in the filesystem. All + added files which were owned by the archive are deleted at this point. On + the issue of ordering, the files are added to the archive in the same order + as they were specified via __file:__. *Note* that this behaviour is new for + version 0.4 and higher. Before 0.4 no specific order was documented. It was + lexicographically sorted. The change was made to support + __[zip](../../../../index.md#zip)__-based file formats which require a + specific order of files in the archive, for example ".epub". + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *zipfile* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[compression](../../../../index.md#compression), [zip](../../../../index.md#zip) + +# CATEGORY + +File + +# COPYRIGHT + +Copyright © 2008-2009 Andreas Kupries ADDED embedded/md/tcllib/files/modules/zip/mkzip.md Index: embedded/md/tcllib/files/modules/zip/mkzip.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/modules/zip/mkzip.md @@ -0,0 +1,141 @@ + +[//000000001]: # (zipfile::mkzip - Zip archive creation) +[//000000002]: # (Generated from file 'mkzip.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (zipfile::mkzip(n) 1.2 tcllib "Zip archive creation") + +# NAME + +zipfile::mkzip - Build a zip archive + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [API](#section2) + + - [Bugs, Ideas, Feedback](#section3) + + - [Keywords](#keywords) + + - [Category](#category) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require Tcl 8.6 +package require zipfile::mkzip ?1.2? + +[__::zipfile::mkzip::mkzip__ *zipfile* ?__-zipkit__? ?__-runtime__ *prefix*? ?__-comment__ *string*? ?__-directory__ *rootpath*? ?__-exclude__ *exclude*? ?__--__? ?*path*...?](#1) + +# DESCRIPTION + +This package utilizes the zlib functions in Tcl 8.6 to build zip archives. + +# API + + - __::zipfile::mkzip::mkzip__ *zipfile* ?__-zipkit__? ?__-runtime__ *prefix*? ?__-comment__ *string*? ?__-directory__ *rootpath*? ?__-exclude__ *exclude*? ?__--__? ?*path*...? + + From [http://wiki.tcl.tk/15158](http://wiki.tcl.tk/15158) + + This command constructs a zip archive from a directory tree using nothing + but Tcl 8.6 core features. The resulting zip file should be compatible with + other __[zip](../../../../index.md#zip)__ programs - with the possible + exception of unicode support. The files generated by this command use utf-8 + encoding for all filenames and comments and it has been noticed particularly + on Windows the __info-zip__ and the Windows built-in zip view have rather + poor support for this part of the ZIP file specification. The __7-Zip__ + program does correctly display utf8 filenames however and the __vfs::zip__ + package will use these of course. + + If you use + + __::mkzip::mkzip__ mystuff.tm -zipkit -directory mystuff.vfs + + it will pack your "mystuff.vfs/" virtual filesystem tree into a zip archive + with a suitable header such that on unix you may mark it executable and it + should run with tclkit. Or you can run it with __tclsh__ or __wish__ 8.6 if + you like. + + To change the executable header, specify the __-runtime__ "preface" where + preface is a file containing code you want prefixed. For instance, on + Windows you can create a self-extracting zip archive using + + mkzip mystuff.exe -directory mystuff.vfs -runtime unzipsfx.exe + + The "unzipsfx.exe" is the Info-Zip self-extracting stub. + + Accepted options: + + * __-runtime__ path + + This option specifies a file to use as prefix to the actual zip archive. + If specified __-zipkit__ will be ignored. + + * __-zipkit__ + + Instructs the command to generate a prefix which makes the archive a + zip-based starkit. Ignored if __-runtime__ is present. + + * __-comment__ string + + This options specifies a global comment to place into the generated + archive. + + * __-directory__ path + + This option specifies the directory to place into the generated archive. + If specified any argument *path*s are *ignored*. + + * __-exclude__ list + + This option specifies a list of glob patterns. All paths matching at + least one of the patterns are not placed into the generated archive. + This option defaults to + + CVS/* */CVS/* *~ ".#*" "*/.#*" + + * __--__ + + This option signals the end of the options, forcing processing of all + further words as arguments, even if they begin with a dash character. + + Accepted arguments: + + * path *path* + + Each path is a directory or file to place into the generated archive. + Note however that these will be ignored when option __-directory__ is + specified. + +# Bugs, Ideas, Feedback + +This document, and the package it describes, will undoubtedly contain bugs and +other problems. Please report such in the category *zipfile* of the [Tcllib +Trackers](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas +for enhancements you may have for either package and/or documentation. + +When proposing code changes, please provide *unified diffs*, i.e the output of +__diff -u__. + +Note further that *attachments* are strongly preferred over inlined patches. +Attachments can be made by going to the __Edit__ form of the ticket immediately +after its creation, and then using the left-most button in the secondary +navigation bar. + +# KEYWORDS + +[decompression](../../../../index.md#decompression), +[zip](../../../../index.md#zip) + +# CATEGORY + +File + +# COPYRIGHT + +Copyright © 2009 Pat Thoyts ADDED embedded/md/tcllib/toc.md Index: embedded/md/tcllib/toc.md ================================================================== --- /dev/null +++ embedded/md/tcllib/toc.md @@ -0,0 +1,862 @@ + +[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown') + +# Table Of Contents -- tcllib + + - [aes](tcllib/files/modules/aes/aes.md) Implementation of the AES block cipher + + - [ascii85](tcllib/files/modules/base64/ascii85.md) ascii85-encode/decode binary data + + - [asn](tcllib/files/modules/asn/asn.md) ASN.1 BER encoder/decoder + + - [autoproxy](tcllib/files/modules/http/autoproxy.md) Automatic HTTP proxy usage and authentication + + - [base32](tcllib/files/modules/base32/base32.md) base32 standard encoding + + - [base32::core](tcllib/files/modules/base32/base32core.md) Expanding basic base32 maps + + - [base32::hex](tcllib/files/modules/base32/base32hex.md) base32 extended hex encoding + + - [base64](tcllib/files/modules/base64/base64.md) base64-encode/decode binary data + + - [bee](tcllib/files/modules/bee/bee.md) BitTorrent Serialization Format Encoder/Decoder + + - [bench](tcllib/files/modules/bench/bench.md) bench - Processing benchmark suites + + - [bench::in](tcllib/files/modules/bench/bench_read.md) bench::in - Reading benchmark results + + - [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) bench::out::csv - Formatting benchmark results as CSV + + - [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) bench::out::text - Formatting benchmark results as human readable text + + - [bench_intro](tcllib/files/modules/bench/bench_intro.md) bench introduction + + - [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) bench language introduction + + - [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md) bench language specification + + - [bibtex](tcllib/files/modules/bibtex/bibtex.md) Parse bibtex files + + - [blowfish](tcllib/files/modules/blowfish/blowfish.md) Implementation of the Blowfish block cipher + + - [cache::async](tcllib/files/modules/cache/async.md) Asynchronous in-memory cache + + - [cksum](tcllib/files/modules/crc/cksum.md) Calculate a cksum(1) compatible checksum + + - [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. + + - [comm](tcllib/files/modules/comm/comm.md) A remote communication facility for Tcl (8.3 and later) + + - [comm_wire](tcllib/files/modules/comm/comm_wire.md) The comm wire protocol + + - [control](tcllib/files/modules/control/control.md) Procedures for control flow structures. + + - [coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) Coroutine based event and IO handling + + - [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) Automatic event and IO coroutine awareness + + - [counter](tcllib/files/modules/counter/counter.md) Procedures for counters and histograms + + - [crc16](tcllib/files/modules/crc/crc16.md) Perform a 16bit Cyclic Redundancy Check + + - [crc32](tcllib/files/modules/crc/crc32.md) Perform a 32bit Cyclic Redundancy Check + + - [cron](tcllib/files/modules/cron/cron.md) Tool for automating the period callback of commands + + - [csv](tcllib/files/modules/csv/csv.md) Procedures to handle CSV data. + + - [debug](tcllib/files/modules/debug/debug.md) debug narrative - core + + - [debug::caller](tcllib/files/modules/debug/debug_caller.md) debug narrative - caller + + - [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) debug narrative - heartbeat + + - [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md) debug narrative - timestamping + + - [defer](tcllib/files/modules/defer/defer.md) Defered execution + + - [deleg_method](tcllib/files/modules/interp/deleg_method.md) Creation of comm delegates (snit methods) + + - [deleg_proc](tcllib/files/modules/interp/deleg_proc.md) Creation of comm delegates (procedures) + + - [des](tcllib/files/modules/des/des.md) Implementation of the DES and triple-DES ciphers + + - [dicttool](tcllib/files/modules/dicttool/dicttool.md) Dictionary Tools + + - [dns](tcllib/files/modules/dns/tcllib_dns.md) Tcl Domain Name Service Client + + - [docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) docidx introduction + + - [docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) docidx language command reference + + - [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) docidx language faq + + - [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) docidx language introduction + + - [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) docidx language syntax + + - [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) docidx plugin API reference + + - [docstrip](tcllib/files/modules/docstrip/docstrip.md) Docstrip style source code extraction + + - [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) Docstrip-related utilities + + - [doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) doctoc introduction + + - [doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) doctoc language command reference + + - [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) doctoc language faq + + - [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) doctoc language introduction + + - [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) doctoc language syntax + + - [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) doctoc plugin API reference + + - [doctools](tcllib/files/modules/doctools/doctools.md) doctools - Processing documents + + - [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) DocTools - Keyword indices + + - [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) DocTools - Tables of Contents + + - [doctools::changelog](tcllib/files/modules/doctools/changelog.md) Processing text in Emacs ChangeLog format + + - [doctools::cvs](tcllib/files/modules/doctools/cvs.md) Processing text in 'cvs log' format + + - [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) Default CSS style for HTML export plugins + + - [doctools::idx](tcllib/files/modules/doctools/docidx.md) docidx - Processing indices + + - [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) Holding keyword indices + + - [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) Exporting keyword indices + + - [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) docidx export plugin + + - [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) HTML export plugin + + - [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) JSON export plugin + + - [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) nroff export plugin + + - [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) plain text export plugin + + - [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) wiki export plugin + + - [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) Importing keyword indices + + - [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) docidx import plugin + + - [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) JSON import plugin + + - [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) Parsing text in docidx format + + - [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) Docidx serialization utilities + + - [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) Message catalog management for the various document parsers + + - [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) Message catalog for the docidx parser (C) + + - [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) Message catalog for the docidx parser (DE) + + - [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) Message catalog for the docidx parser (EN) + + - [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) Message catalog for the docidx parser (FR) + + - [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) Message catalog for the doctoc parser (C) + + - [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) Message catalog for the doctoc parser (DE) + + - [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) Message catalog for the doctoc parser (EN) + + - [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md) Message catalog for the doctoc parser (FR) + + - [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) Default CSS style for NROFF export plugins + + - [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) Processing text in 'subst -novariables' format + + - [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) Holding tables of contents + + - [doctools::toc](tcllib/files/modules/doctools/doctoc.md) doctoc - Processing tables of contents + + - [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) Exporting tables of contents + + - [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) doctoc export plugin + + - [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) HTML export plugin + + - [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) JSON export plugin + + - [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) nroff export plugin + + - [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) plain text export plugin + + - [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) wiki export plugin + + - [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) Importing keyword indices + + - [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) doctoc import plugin + + - [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) JSON import plugin + + - [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) Parsing text in doctoc format + + - [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) Doctoc serialization utilities + + - [doctools_intro](tcllib/files/modules/doctools/doctools_intro.md) doctools introduction + + - [doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) doctools language command reference + + - [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) doctools language faq + + - [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) doctools language introduction + + - [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md) doctools language syntax + + - [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md) doctools plugin API reference + + - [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) Lightweight DocTools Markup Processor + + - [dtplite](tcllib/files/apps/dtplite.md) Lightweight DocTools Markup Processor + + - [fileutil](tcllib/files/modules/fileutil/fileutil.md) Procedures implementing some file utilities + + - [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) Generator core for compiler of magic(5) files + + - [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) Generator core for compiler of magic(5) files + + - [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) Procedures implementing file-type recognition + + - [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) Runtime core for file type recognition engines written in pure Tcl + + - [fileutil::multi](tcllib/files/modules/fileutil/multi.md) Multi-file operation, scatter/gather, standard object + + - [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md) Multi-file operation, scatter/gather + + - [fileutil_traverse](tcllib/files/modules/fileutil/traverse.md) Iterative directory traversal + + - [ftp](tcllib/files/modules/ftp/ftp.md) Client-side tcl implementation of the ftp protocol + + - [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) Uri handler for ftp urls + + - [ftpd](tcllib/files/modules/ftpd/ftpd.md) Tcl FTP server implementation + + - [generator](tcllib/files/modules/generator/generator.md) Procedures for creating and using generators. + + - [gpx](tcllib/files/modules/gpx/gpx.md) Extracts waypoints, tracks and routes from GPX files + + - [grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) Aycock-Horspool-Earley parser generator for Tcl + + - [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) Create and manipulate finite automatons + + - [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) Create and use deterministic acceptors + + - [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) Execute deterministic finite automatons + + - [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) Operations on finite automatons + + - [grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) Virtual machine implementation II for parsing token streams + + - [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) ME virtual machine state manipulation + + - [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) ME assembler + + - [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) Virtual machine implementation I for parsing token streams + + - [grammar::me::util](tcllib/files/modules/grammar_me/me_util.md) AST utilities + + - [grammar::me_ast](tcllib/files/modules/grammar_me/me_ast.md) Various representations of ASTs + + - [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) Introduction to virtual machines for parsing token streams + + - [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) Virtual machine for parsing token streams + + - [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) Create and manipulate parsing expression grammars + + - [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) Interpreter for parsing expression grammars + + - [hook](tcllib/files/modules/hook/hook.md) Hooks + + - [html](tcllib/files/modules/html/html.md) Procedures to generate HTML structures + + - [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) Procedures to parse HTML strings + + - [huddle](tcllib/files/modules/yaml/huddle.md) Create and manipulate huddle object + + - [ident](tcllib/files/modules/ident/ident.md) Ident protocol client + + - [imap4](tcllib/files/modules/imap4/imap4.md) imap client-side tcl implementation of imap protocol + + - [inifile](tcllib/files/modules/inifile/ini.md) Parsing of Windows INI files + + - [interp](tcllib/files/modules/interp/tcllib_interp.md) Interp creation and aliasing + + - [irc](tcllib/files/modules/irc/irc.md) Create IRC connection and interface. + + - [javascript](tcllib/files/modules/javascript/javascript.md) Procedures to generate HTML and Java Script structures. + + - [jpeg](tcllib/files/modules/jpeg/jpeg.md) JPEG querying and manipulation of meta data + + - [json](tcllib/files/modules/json/json.md) JSON parser + + - [json::write](tcllib/files/modules/json/json_write.md) JSON generation + + - [lambda](tcllib/files/modules/lambda/lambda.md) Utility commands for anonymous procedures + + - [lazyset](tcllib/files/modules/lazyset/lazyset.md) Lazy evaluation + + - [ldap](tcllib/files/modules/ldap/ldap.md) LDAP client + + - [ldapx](tcllib/files/modules/ldap/ldapx.md) LDAP extended object interface + + - [log](tcllib/files/modules/log/log.md) Procedures to log messages of libraries and applications. + + - [logger](tcllib/files/modules/log/logger.md) System to control logging of events. + + - [logger::appender](tcllib/files/modules/log/loggerAppender.md) Collection of predefined appenders for logger + + - [logger::utils](tcllib/files/modules/log/loggerUtils.md) Utilities for logger + + - [map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) Resolving geographical names with a Nominatim service + + - [map::slippy](tcllib/files/modules/map/map_slippy.md) Common code for slippy based map packages + + - [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) Management of a tile cache in the local filesystem + + - [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) Accessing a server providing tiles for slippy-based maps + + - [mapproj](tcllib/files/modules/mapproj/mapproj.md) Map projection routines + + - [markdown](tcllib/files/modules/markdown/markdown.md) Converts Markdown text to HTML + + - [math](tcllib/files/modules/math/math.md) Tcl Math Library + + - [math::bigfloat](tcllib/files/modules/math/bigfloat.md) Arbitrary precision floating-point numbers + + - [math::bignum](tcllib/files/modules/math/bignum.md) Arbitrary precision integer numbers + + - [math::calculus](tcllib/files/modules/math/calculus.md) Integration and ordinary differential equations + + - [math::calculus::romberg](tcllib/files/modules/math/romberg.md) Romberg integration + + - [math::calculus::symdiff](tcllib/files/modules/math/symdiff.md) Symbolic differentiation for Tcl + + - [math::combinatorics](tcllib/files/modules/math/combinatorics.md) Combinatorial functions in the Tcl Math Library + + - [math::complexnumbers](tcllib/files/modules/math/qcomplex.md) Straightforward complex number package + + - [math::constants](tcllib/files/modules/math/constants.md) Mathematical and numerical constants + + - [math::decimal](tcllib/files/modules/math/decimal.md) General decimal arithmetic + + - [math::exact](tcllib/files/modules/math/exact.md) Exact Real Arithmetic + + - [math::fourier](tcllib/files/modules/math/fourier.md) Discrete and fast fourier transforms + + - [math::fuzzy](tcllib/files/modules/math/fuzzy.md) Fuzzy comparison of floating-point numbers + + - [math::geometry](tcllib/files/modules/math/math_geometry.md) Geometrical computations + + - [math::interpolate](tcllib/files/modules/math/interpolate.md) Interpolation routines + + - [math::linearalgebra](tcllib/files/modules/math/linalg.md) Linear Algebra + + - [math::numtheory](tcllib/files/modules/math/numtheory.md) Number Theory + + - [math::optimize](tcllib/files/modules/math/optimize.md) Optimisation routines + + - [math::PCA](tcllib/files/modules/math/pca.md) Package for Principal Component Analysis + + - [math::polynomials](tcllib/files/modules/math/polynomials.md) Polynomial functions + + - [math::rationalfunctions](tcllib/files/modules/math/rational_funcs.md) Polynomial functions + + - [math::roman](tcllib/files/modules/math/roman.md) Tools for creating and manipulating roman numerals + + - [math::special](tcllib/files/modules/math/special.md) Special mathematical functions + + - [math::statistics](tcllib/files/modules/math/statistics.md) Basic statistical functions and procedures + + - [math::trig](tcllib/files/modules/math/trig.md) Trigonometric anf hyperbolic functions + + - [md4](tcllib/files/modules/md4/md4.md) MD4 Message-Digest Algorithm + + - [md5](tcllib/files/modules/md5/md5.md) MD5 Message-Digest Algorithm + + - [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) MD5-based password encryption + + - [mime](tcllib/files/modules/mime/mime.md) Manipulation of MIME body parts + + - [mpexpand](tcllib/files/modules/doctools/mpexpand.md) Markup processor + + - [multiplexer](tcllib/files/modules/multiplexer/multiplexer.md) One-to-many communication with sockets. + + - [nameserv](tcllib/files/modules/nns/nns_client.md) Name service facility, Client + + - [nameserv::auto](tcllib/files/modules/nns/nns_auto.md) Name service facility, Client Extension + + - [nameserv::common](tcllib/files/modules/nns/nns_common.md) Name service facility, shared definitions + + - [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md) Name service facility, client/server protocol + + - [nameserv::server](tcllib/files/modules/nns/nns_server.md) Name service facility, Server + + - [namespacex](tcllib/files/modules/namespacex/namespacex.md) Namespace utility commands + + - [ncgi](tcllib/files/modules/ncgi/ncgi.md) Procedures to manipulate CGI values. + + - [nettool](tcllib/files/modules/nettool/nettool.md) Tools for networked applications + + - [nmea](tcllib/files/modules/nmea/nmea.md) Process NMEA data + + - [nns](tcllib/files/apps/nns.md) Name service facility, Commandline Client Application + + - [nns_intro](tcllib/files/modules/nns/nns_intro.md) Name service facility, introduction + + - [nnsd](tcllib/files/apps/nnsd.md) Name service facility, Commandline Server Application + + - [nnslog](tcllib/files/apps/nnslog.md) Name service facility, Commandline Logging Client Application + + - [nntp](tcllib/files/modules/nntp/nntp.md) Tcl client for the NNTP protocol + + - [ntp_time](tcllib/files/modules/ntp/ntp_time.md) Tcl Time Service Client + + - [oauth](tcllib/files/modules/oauth/oauth.md) oauth API base signature + + - [oo::util](tcllib/files/modules/tool/meta.md) Utility commands for TclOO + + - [oo::util](tcllib/files/modules/ooutil/ooutil.md) Utility commands for TclOO + + - [oometa](tcllib/files/modules/oometa/oometa.md) oo::meta A data registry for classess + + - [otp](tcllib/files/modules/otp/otp.md) One-Time Passwords + + - [page](tcllib/files/apps/page.md) Parser Generator + + - [page_intro](tcllib/files/modules/page/page_intro.md) page introduction + + - [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) page plugin manager + + - [page_util_flow](tcllib/files/modules/page/page_util_flow.md) page dataflow/treewalker utility + + - [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) page AST normalization, LEMON + + - [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) page AST normalization, PEG + + - [page_util_peg](tcllib/files/modules/page/page_util_peg.md) page PEG transformation utilities + + - [page_util_quote](tcllib/files/modules/page/page_util_quote.md) page character quoting utilities + + - [picoirc](tcllib/files/modules/irc/picoirc.md) Small and simple embeddable IRC client. + + - [pki](tcllib/files/modules/pki/pki.md) Implementation of the public key cipher + + - [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr.md) Manage a plugin + + - [png](tcllib/files/modules/png/png.md) PNG querying and manipulation of meta data + + - [pop3](tcllib/files/modules/pop3/pop3.md) Tcl client for POP3 email protocol + + - [pop3d](tcllib/files/modules/pop3d/pop3d.md) Tcl POP3 server implementation + + - [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) Simple mailbox database for pop3d + + - [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md) Simple user database for pop3d + + - [practcl](tcllib/files/modules/practcl/practcl.md) The Practcl Module + + - [processman](tcllib/files/modules/processman/processman.md) Tool for automating the period callback of commands + + - [profiler](tcllib/files/modules/profiler/profiler.md) Tcl source code profiler + + - [pt](tcllib/files/apps/pt.md) Parser Tools Application + + - [pt::ast](tcllib/files/modules/pt/pt_astree.md) Abstract Syntax Tree Serialization + + - [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) C/PARAM, Canned configuration, Critcl + + - [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) C/PARAM, Canned configuration, TEA + + - [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) The JSON Grammar Exchange Format + + - [pt::param](tcllib/files/modules/pt/pt_param.md) PackRat Machine Specification + + - [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) Parsing Expression Serialization + + - [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) Parsing Expression Utilities + + - [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) Parsing Expression Grammar Serialization + + - [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) PEG Storage + + - [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) PEG Storage. Canned PEG grammar specification + + - [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) PEG Export + + - [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) PEG Export Plugin. Write CONTAINER format + + - [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) PEG Export Plugin. Write JSON format + + - [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) PEG Export Plugin. Write PEG format + + - [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) PEG Conversion. From CONTAINER format + + - [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) PEG Conversion. Read JSON format + + - [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) PEG Conversion. Read PEG format + + - [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) PEG Import + + - [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) PEG Import Plugin. From CONTAINER format + + - [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) PEG Import Plugin. Read JSON format + + - [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) PEG Import Plugin. Read PEG format + + - [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) Interpreter for parsing expression grammars + + - [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) PEG Conversion. Write CONTAINER format + + - [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) PEG Conversion. Write CPARAM format + + - [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) PEG Conversion. Write JSON format + + - [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) PEG Conversion. Write PARAM format + + - [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) PEG Conversion. Write PEG format + + - [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) PEG Conversion. Write TCLPARAM format + + - [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) PEG Language Tutorial + + - [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) Introduction to Parsing Expression Grammars + + - [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) Parser Generator + + - [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) Parsing Runtime Support, PARAM based + + - [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) Tcl/PARAM, Canned configuration, NX + + - [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) Tcl/PARAM, Canned configuration, Snit + + - [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) Tcl/PARAM, Canned configuration, Tcloo + + - [pt::util](tcllib/files/modules/pt/pt_util.md) General utilities + + - [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) Parser Tools Export API + + - [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) Parser Tools Import API + + - [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) Introduction to Parser Tools + + - [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) Parser Tools PEG Parser + + - [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) Parser API + + - [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md) Parser Tools PE Grammar Utility Operations + + - [rc4](tcllib/files/modules/rc4/rc4.md) Implementation of the RC4 stream cipher + + - [rcs](tcllib/files/modules/rcs/rcs.md) RCS low level utilities + + - [report](tcllib/files/modules/report/report.md) Create and manipulate report objects + + - [rest](tcllib/files/modules/rest/rest.md) define REST web APIs and call them inline or asychronously + + - [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) RIPEMD-128 Message-Digest Algorithm + + - [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) RIPEMD-160 Message-Digest Algorithm + + - [S3](tcllib/files/modules/amazon-s3/S3.md) Amazon S3 Web Service Interface + + - [SASL](tcllib/files/modules/sasl/sasl.md) Implementation of SASL mechanisms for Tcl + + - [SASL::NTLM](tcllib/files/modules/sasl/ntlm.md) Implementation of SASL NTLM mechanism for Tcl + + - [SASL::SCRAM](tcllib/files/modules/sasl/scram.md) Implementation of SASL SCRAM mechanism for Tcl + + - [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md) Implementation of SASL NTLM mechanism for Tcl + + - [sha1](tcllib/files/modules/sha1/sha1.md) SHA1 Message-Digest Algorithm + + - [sha256](tcllib/files/modules/sha1/sha256.md) SHA256 Message-Digest Algorithm + + - [simulation::annealing](tcllib/files/modules/simulation/annealing.md) Simulated annealing + + - [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md) Monte Carlo simulations + + - [simulation::random](tcllib/files/modules/simulation/simulation_random.md) Pseudo-random number generators + + - [smtp](tcllib/files/modules/mime/smtp.md) Client-side tcl implementation of the smtp protocol + + - [smtpd](tcllib/files/modules/smtpd/smtpd.md) Tcl SMTP server implementation + + - [snit](tcllib/files/modules/snit/snit.md) Snit's Not Incr Tcl + + - [snitfaq](tcllib/files/modules/snit/snitfaq.md) Snit Frequently Asked Questions + + - [soundex](tcllib/files/modules/soundex/soundex.md) Soundex + + - [stooop](tcllib/files/modules/stooop/stooop.md) Object oriented extension. + + - [string::token](tcllib/files/modules/string/token.md) Regex based iterative lexing + + - [string::token::shell](tcllib/files/modules/string/token_shell.md) Parsing of shell command line + + - [stringprep](tcllib/files/modules/stringprep/stringprep.md) Implementation of stringprep + + - [stringprep::data](tcllib/files/modules/stringprep/stringprep_data.md) stringprep data tables, generated, internal + + - [struct::disjointset](tcllib/files/modules/struct/disjointset.md) Disjoint set data structure + + - [struct::graph](tcllib/files/modules/struct/graph.md) Create and manipulate directed graph objects + + - [struct::graph::op](tcllib/files/modules/struct/graphops.md) Operation for (un)directed graph objects + + - [struct::graph_v1](tcllib/files/modules/struct/graph1.md) Create and manipulate directed graph objects + + - [struct::list](tcllib/files/modules/struct/struct_list.md) Procedures for manipulating lists + + - [struct::matrix](tcllib/files/modules/struct/matrix.md) Create and manipulate matrix objects + + - [struct::matrix_v1](tcllib/files/modules/struct/matrix1.md) Create and manipulate matrix objects + + - [struct::pool](tcllib/files/modules/struct/pool.md) Create and manipulate pool objects (of discrete items) + + - [struct::prioqueue](tcllib/files/modules/struct/prioqueue.md) Create and manipulate prioqueue objects + + - [struct::queue](tcllib/files/modules/struct/queue.md) Create and manipulate queue objects + + - [struct::record](tcllib/files/modules/struct/record.md) Define and create records (similar to 'C' structures) + + - [struct::set](tcllib/files/modules/struct/struct_set.md) Procedures for manipulating sets + + - [struct::skiplist](tcllib/files/modules/struct/skiplist.md) Create and manipulate skiplists + + - [struct::stack](tcllib/files/modules/struct/stack.md) Create and manipulate stack objects + + - [struct::tree](tcllib/files/modules/struct/struct_tree.md) Create and manipulate tree objects + + - [struct::tree_v1](tcllib/files/modules/struct/struct_tree1.md) Create and manipulate tree objects + + - [sum](tcllib/files/modules/crc/sum.md) Calculate a sum(1) compatible checksum + + - [switched](tcllib/files/modules/stooop/switched.md) switch/option management. + + - [tar](tcllib/files/modules/tar/tar.md) Tar file creation, extraction & manipulation + + - [tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) Concatenation channel + + - [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) Basic reflected/virtual channel support + + - [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) Event support for reflected/virtual channels + + - [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) Facade channel + + - [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) In-memory fifo channel + + - [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) In-memory interconnected fifo channels + + - [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) In-memory channel, half of a fifo2 + + - [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) In-memory channel + + - [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) Null channel + + - [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) Null/Zero channel combination + + - [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) Random channel + + - [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) Standard I/O, unification of stdin and stdout + + - [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) Read-only in-memory channel + + - [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) Textwindow channel + + - [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) In-memory channel using variable for storage + + - [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) Zero channel + + - [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) Utilities for random channels + + - [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) Adler32 transformation + + - [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) Base64 encoding transformation + + - [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md) Basic reflected/virtual channel transform support + + - [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) Counter transformation + + - [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) Crc32 transformation + + - [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) Hexadecimal encoding transformation + + - [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) Identity transformation + + - [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) limiting input + + - [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) Observer transformation, stream copy + + - [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) Encryption via one-time pad + + - [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) rot-encryption + + - [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) Space insertation and removal + + - [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md) zlib (de)compression + + - [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_ip](tcllib/files/modules/dns/tcllib_ip.md) IPv4 and IPv6 address manipulation + + - [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 + + - [tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md) TEPAM DOC Generation, reference manual + + - [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md) TEPAM procedure, reference manual + + - [term](tcllib/files/modules/term/term.md) General terminal control + + - [term::ansi::code](tcllib/files/modules/term/ansi_code.md) Helper for control sequences + + - [term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) ANSI attribute sequences + + - [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) ANSI control sequences + + - [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) Macro sequences + + - [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md) Control operations and queries + + - [term::ansi::send](tcllib/files/modules/term/ansi_send.md) Output of ANSI control sequences to terminals + + - [term::interact::menu](tcllib/files/modules/term/imenu.md) Terminal widget, menu + + - [term::interact::pager](tcllib/files/modules/term/ipager.md) Terminal widget, paging + + - [term::receive](tcllib/files/modules/term/receive.md) General input from terminals + + - [term::receive::bind](tcllib/files/modules/term/term_bind.md) Keyboard dispatch from terminals + + - [term::send](tcllib/files/modules/term/term_send.md) General output to terminals + + - [textutil](tcllib/files/modules/textutil/textutil.md) Procedures to manipulate texts and strings. + + - [textutil::adjust](tcllib/files/modules/textutil/adjust.md) Procedures to adjust, indent, and undent paragraphs + + - [textutil::expander](tcllib/files/modules/textutil/expander.md) Procedures to process templates and expand text. + + - [textutil::repeat](tcllib/files/modules/textutil/repeat.md) Procedures to repeat strings. + + - [textutil::split](tcllib/files/modules/textutil/textutil_split.md) Procedures to split texts + + - [textutil::string](tcllib/files/modules/textutil/textutil_string.md) Procedures to manipulate texts and strings. + + - [textutil::tabify](tcllib/files/modules/textutil/tabify.md) Procedures to (un)tabify strings + + - [textutil::trim](tcllib/files/modules/textutil/trim.md) Procedures to trim strings + + - [throw](tcllib/files/modules/try/tcllib_throw.md) throw - Throw an error exception with a message + + - [tie](tcllib/files/modules/tie/tie_std.md) Array persistence, standard data sources + + - [tie](tcllib/files/modules/tie/tie.md) Array persistence + + - [tiff](tcllib/files/modules/tiff/tiff.md) TIFF reading, writing, and querying and manipulation of meta data + + - [tool](tcllib/files/modules/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 + + - [transfer::copy](tcllib/files/modules/transfer/copyops.md) Data transfer foundation + + - [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) Queued transfers + + - [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) Data destination + + - [transfer::data::source](tcllib/files/modules/transfer/dsource.md) Data source + + - [transfer::receiver](tcllib/files/modules/transfer/receiver.md) Data source + + - [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md) Data source + + - [treeql](tcllib/files/modules/treeql/treeql.md) Query tree objects + + - [try](tcllib/files/modules/try/tcllib_try.md) try - Trap and process errors and exceptions + + - [udpcluster](tcllib/files/modules/udpcluster/udpcluster.md) UDP Peer-to-Peer cluster + + - [uevent](tcllib/files/modules/uev/uevent.md) User events + + - [uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md) Request merging and deferal to idle time + + - [unicode](tcllib/files/modules/stringprep/unicode.md) Implementation of Unicode normalization + + - [unicode::data](tcllib/files/modules/stringprep/unicode_data.md) unicode data tables, generated, internal + + - [units](tcllib/files/modules/units/units.md) unit conversion + + - [uri](tcllib/files/modules/uri/uri.md) URI utilities + + - [uri_urn](tcllib/files/modules/uri/urn-scheme.md) URI utilities, URN scheme + + - [uuencode](tcllib/files/modules/base64/uuencode.md) UU-encode/decode binary data + + - [uuid](tcllib/files/modules/uuid/uuid.md) UUID generation and comparison + + - [valtype::common](tcllib/files/modules/valtype/valtype_common.md) Validation, common code + + - [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) Validation for AMEX creditcard number + + - [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) Validation for Discover creditcard number + + - [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) Validation for Mastercard creditcard number + + - [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) Validation for VISA creditcard number + + - [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) Validation for EAN13 + + - [valtype::iban](tcllib/files/modules/valtype/iban.md) Validation for IBAN + + - [valtype::imei](tcllib/files/modules/valtype/imei.md) Validation for IMEI + + - [valtype::isbn](tcllib/files/modules/valtype/isbn.md) Validation for ISBN + + - [valtype::luhn](tcllib/files/modules/valtype/luhn.md) Validation for plain number with a LUHN checkdigit + + - [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) Validation for plain number with a LUHN5 checkdigit + + - [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) Validation for USNPI + + - [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md) Validation for plain number with a VERHOEFF checkdigit + + - [websocket](tcllib/files/modules/websocket/websocket.md) Tcl implementation of the websocket protocol + + - [wip](tcllib/files/modules/wip/wip.md) Word Interpreter + + - [xsxp](tcllib/files/modules/amazon-s3/xsxp.md) eXtremely Simple Xml Parser + + - [yaml](tcllib/files/modules/yaml/yaml.md) YAML Format Encoder/Decoder + + - [yencode](tcllib/files/modules/base64/yencode.md) Y-encode/decode binary data + + - [zipfile::decode](tcllib/files/modules/zip/decode.md) Access to zip archives + + - [zipfile::encode](tcllib/files/modules/zip/encode.md) Generation of zip archives + + - [zipfile::mkzip](tcllib/files/modules/zip/mkzip.md) Build a zip archive ADDED embedded/md/toc.md Index: embedded/md/toc.md ================================================================== --- /dev/null +++ embedded/md/toc.md @@ -0,0 +1,2034 @@ + +[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown') + +# Table Of Contents -- + + - [By Categories]() + + * [Argument entry form, mega widget]() + + + [tepam::argument_dialogbox](tcllib/files/modules/tepam/tepam_argument_dialogbox.md) TEPAM argument_dialogbox, reference manual + + * [Benchmark tools]() + + + [bench](tcllib/files/modules/bench/bench.md) bench - Processing benchmark suites + + + [bench::in](tcllib/files/modules/bench/bench_read.md) bench::in - Reading benchmark results + + + [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) bench::out::csv - Formatting benchmark results as CSV + + + [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) bench::out::text - Formatting benchmark results as human readable text + + + [bench_intro](tcllib/files/modules/bench/bench_intro.md) bench introduction + + + [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) bench language introduction + + + [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md) bench language specification + + * [CGI programming]() + + + [html](tcllib/files/modules/html/html.md) Procedures to generate HTML structures + + + [javascript](tcllib/files/modules/javascript/javascript.md) Procedures to generate HTML and Java Script structures. + + + [json](tcllib/files/modules/json/json.md) JSON parser + + + [json::write](tcllib/files/modules/json/json_write.md) JSON generation + + + [ncgi](tcllib/files/modules/ncgi/ncgi.md) Procedures to manipulate CGI values. + + * [Channels]() + + + [tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) Concatenation channel + + + [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) Basic reflected/virtual channel support + + + [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) Event support for reflected/virtual channels + + + [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) Facade channel + + + [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) In-memory fifo channel + + + [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) In-memory interconnected fifo channels + + + [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) In-memory channel, half of a fifo2 + + + [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) In-memory channel + + + [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) Null channel + + + [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) Null/Zero channel combination + + + [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) Random channel + + + [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) Standard I/O, unification of stdin and stdout + + + [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) Read-only in-memory channel + + + [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) Textwindow channel + + + [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) In-memory channel using variable for storage + + + [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) Zero channel + + + [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) Utilities for random channels + + + [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) Adler32 transformation + + + [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) Base64 encoding transformation + + + [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md) Basic reflected/virtual channel transform support + + + [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) Counter transformation + + + [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) Crc32 transformation + + + [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) Hexadecimal encoding transformation + + + [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) Identity transformation + + + [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) limiting input + + + [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) Observer transformation, stream copy + + + [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) Encryption via one-time pad + + + [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) rot-encryption + + + [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) Space insertation and removal + + + [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md) zlib (de)compression + + * [Coroutine]() + + + [coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) Coroutine based event and IO handling + + + [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) Automatic event and IO coroutine awareness + + * [Data structures]() + + + [counter](tcllib/files/modules/counter/counter.md) Procedures for counters and histograms + + + [report](tcllib/files/modules/report/report.md) Create and manipulate report objects + + + [struct::disjointset](tcllib/files/modules/struct/disjointset.md) Disjoint set data structure + + + [struct::graph](tcllib/files/modules/struct/graph.md) Create and manipulate directed graph objects + + + [struct::graph::op](tcllib/files/modules/struct/graphops.md) Operation for (un)directed graph objects + + + [struct::graph_v1](tcllib/files/modules/struct/graph1.md) Create and manipulate directed graph objects + + + [struct::list](tcllib/files/modules/struct/struct_list.md) Procedures for manipulating lists + + + [struct::matrix](tcllib/files/modules/struct/matrix.md) Create and manipulate matrix objects + + + [struct::matrix_v1](tcllib/files/modules/struct/matrix1.md) Create and manipulate matrix objects + + + [struct::pool](tcllib/files/modules/struct/pool.md) Create and manipulate pool objects (of discrete items) + + + [struct::prioqueue](tcllib/files/modules/struct/prioqueue.md) Create and manipulate prioqueue objects + + + [struct::queue](tcllib/files/modules/struct/queue.md) Create and manipulate queue objects + + + [struct::record](tcllib/files/modules/struct/record.md) Define and create records (similar to 'C' structures) + + + [struct::set](tcllib/files/modules/struct/struct_set.md) Procedures for manipulating sets + + + [struct::skiplist](tcllib/files/modules/struct/skiplist.md) Create and manipulate skiplists + + + [struct::stack](tcllib/files/modules/struct/stack.md) Create and manipulate stack objects + + + [struct::tree](tcllib/files/modules/struct/struct_tree.md) Create and manipulate tree objects + + + [struct::tree_v1](tcllib/files/modules/struct/struct_tree1.md) Create and manipulate tree objects + + + [treeql](tcllib/files/modules/treeql/treeql.md) Query tree objects + + * [debugging, tracing, and logging]() + + + [debug](tcllib/files/modules/debug/debug.md) debug narrative - core + + + [debug::caller](tcllib/files/modules/debug/debug_caller.md) debug narrative - caller + + + [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) debug narrative - heartbeat + + + [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md) debug narrative - timestamping + + * [Documentation tools]() + + + [docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) docidx introduction + + + [docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) docidx language command reference + + + [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) docidx language faq + + + [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) docidx language introduction + + + [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) docidx language syntax + + + [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) docidx plugin API reference + + + [docstrip](tcllib/files/modules/docstrip/docstrip.md) Docstrip style source code extraction + + + [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) Docstrip-related utilities + + + [doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) doctoc introduction + + + [doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) doctoc language command reference + + + [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) doctoc language faq + + + [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) doctoc language introduction + + + [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) doctoc language syntax + + + [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) doctoc plugin API reference + + + [doctools](tcllib/files/modules/doctools/doctools.md) doctools - Processing documents + + + [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) DocTools - Keyword indices + + + [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) DocTools - Tables of Contents + + + [doctools::changelog](tcllib/files/modules/doctools/changelog.md) Processing text in Emacs ChangeLog format + + + [doctools::cvs](tcllib/files/modules/doctools/cvs.md) Processing text in 'cvs log' format + + + [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) Default CSS style for HTML export plugins + + + [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) Holding keyword indices + + + [doctools::idx](tcllib/files/modules/doctools/docidx.md) docidx - Processing indices + + + [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) Exporting keyword indices + + + [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) Importing keyword indices + + + [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) Parsing text in docidx format + + + [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) Docidx serialization utilities + + + [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) Message catalog management for the various document parsers + + + [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) Message catalog for the docidx parser (C) + + + [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) Message catalog for the docidx parser (DE) + + + [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) Message catalog for the docidx parser (EN) + + + [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) Message catalog for the docidx parser (FR) + + + [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) Message catalog for the doctoc parser (C) + + + [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) Message catalog for the doctoc parser (DE) + + + [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) Message catalog for the doctoc parser (EN) + + + [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md) Message catalog for the doctoc parser (FR) + + + [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) Default CSS style for NROFF export plugins + + + [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) Processing text in 'subst -novariables' format + + + [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) Holding tables of contents + + + [doctools::toc](tcllib/files/modules/doctools/doctoc.md) doctoc - Processing tables of contents + + + [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) Exporting tables of contents + + + [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) Importing keyword indices + + + [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) Parsing text in doctoc format + + + [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) Doctoc serialization utilities + + + [doctools_intro](tcllib/files/modules/doctools/doctools_intro.md) doctools introduction + + + [doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) doctools language command reference + + + [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) doctools language faq + + + [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) doctools language introduction + + + [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md) doctools language syntax + + + [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md) doctools plugin API reference + + + [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) Lightweight DocTools Markup Processor + + + [dtplite](tcllib/files/apps/dtplite.md) Lightweight DocTools Markup Processor + + + [mpexpand](tcllib/files/modules/doctools/mpexpand.md) Markup processor + + + [tcldocstrip](tcllib/files/apps/tcldocstrip.md) Tcl-based Docstrip Processor + + + [tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md) TEPAM DOC Generation, reference manual + + + [textutil::expander](tcllib/files/modules/textutil/expander.md) Procedures to process templates and expand text. + + * [File]() + + + [zipfile::decode](tcllib/files/modules/zip/decode.md) Access to zip archives + + + [zipfile::encode](tcllib/files/modules/zip/encode.md) Generation of zip archives + + + [zipfile::mkzip](tcllib/files/modules/zip/mkzip.md) Build a zip archive + + * [File formats]() + + + [gpx](tcllib/files/modules/gpx/gpx.md) Extracts waypoints, tracks and routes from GPX files + + + [jpeg](tcllib/files/modules/jpeg/jpeg.md) JPEG querying and manipulation of meta data + + + [png](tcllib/files/modules/png/png.md) PNG querying and manipulation of meta data + + + [tar](tcllib/files/modules/tar/tar.md) Tar file creation, extraction & manipulation + + + [tiff](tcllib/files/modules/tiff/tiff.md) TIFF reading, writing, and querying and manipulation of meta data + + * [Grammars and finite automata]() + + + [grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) Aycock-Horspool-Earley parser generator for Tcl + + + [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) Create and manipulate finite automatons + + + [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) Create and use deterministic acceptors + + + [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) Execute deterministic finite automatons + + + [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) Operations on finite automatons + + + [grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) Virtual machine implementation II for parsing token streams + + + [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) ME virtual machine state manipulation + + + [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) ME assembler + + + [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) Virtual machine implementation I for parsing token streams + + + [grammar::me::util](tcllib/files/modules/grammar_me/me_util.md) AST utilities + + + [grammar::me_ast](tcllib/files/modules/grammar_me/me_ast.md) Various representations of ASTs + + + [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) Introduction to virtual machines for parsing token streams + + + [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) Virtual machine for parsing token streams + + + [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) Create and manipulate parsing expression grammars + + + [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) Interpreter for parsing expression grammars + + * [Hashes, checksums, and encryption]() + + + [aes](tcllib/files/modules/aes/aes.md) Implementation of the AES block cipher + + + [blowfish](tcllib/files/modules/blowfish/blowfish.md) Implementation of the Blowfish block cipher + + + [cksum](tcllib/files/modules/crc/cksum.md) Calculate a cksum(1) compatible checksum + + + [crc16](tcllib/files/modules/crc/crc16.md) Perform a 16bit Cyclic Redundancy Check + + + [crc32](tcllib/files/modules/crc/crc32.md) Perform a 32bit Cyclic Redundancy Check + + + [des](tcllib/files/modules/des/des.md) Implementation of the DES and triple-DES ciphers + + + [md4](tcllib/files/modules/md4/md4.md) MD4 Message-Digest Algorithm + + + [md5](tcllib/files/modules/md5/md5.md) MD5 Message-Digest Algorithm + + + [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) MD5-based password encryption + + + [otp](tcllib/files/modules/otp/otp.md) One-Time Passwords + + + [pki](tcllib/files/modules/pki/pki.md) Implementation of the public key cipher + + + [rc4](tcllib/files/modules/rc4/rc4.md) Implementation of the RC4 stream cipher + + + [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) RIPEMD-128 Message-Digest Algorithm + + + [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) RIPEMD-160 Message-Digest Algorithm + + + [sha1](tcllib/files/modules/sha1/sha1.md) SHA1 Message-Digest Algorithm + + + [sha256](tcllib/files/modules/sha1/sha256.md) SHA256 Message-Digest Algorithm + + + [soundex](tcllib/files/modules/soundex/soundex.md) Soundex + + + [sum](tcllib/files/modules/crc/sum.md) Calculate a sum(1) compatible checksum + + + [tclDES](tcllib/files/modules/des/tcldes.md) Implementation of the DES and triple-DES ciphers + + + [tclDESjr](tcllib/files/modules/des/tcldesjr.md) Implementation of the DES and triple-DES ciphers + + + [uuid](tcllib/files/modules/uuid/uuid.md) UUID generation and comparison + + * [Mathematics]() + + + [math](tcllib/files/modules/math/math.md) Tcl Math Library + + + [math::bigfloat](tcllib/files/modules/math/bigfloat.md) Arbitrary precision floating-point numbers + + + [math::bignum](tcllib/files/modules/math/bignum.md) Arbitrary precision integer numbers + + + [math::calculus](tcllib/files/modules/math/calculus.md) Integration and ordinary differential equations + + + [math::calculus::romberg](tcllib/files/modules/math/romberg.md) Romberg integration + + + [math::combinatorics](tcllib/files/modules/math/combinatorics.md) Combinatorial functions in the Tcl Math Library + + + [math::complexnumbers](tcllib/files/modules/math/qcomplex.md) Straightforward complex number package + + + [math::constants](tcllib/files/modules/math/constants.md) Mathematical and numerical constants + + + [math::decimal](tcllib/files/modules/math/decimal.md) General decimal arithmetic + + + [math::exact](tcllib/files/modules/math/exact.md) Exact Real Arithmetic + + + [math::fourier](tcllib/files/modules/math/fourier.md) Discrete and fast fourier transforms + + + [math::fuzzy](tcllib/files/modules/math/fuzzy.md) Fuzzy comparison of floating-point numbers + + + [math::geometry](tcllib/files/modules/math/math_geometry.md) Geometrical computations + + + [math::interpolate](tcllib/files/modules/math/interpolate.md) Interpolation routines + + + [math::linearalgebra](tcllib/files/modules/math/linalg.md) Linear Algebra + + + [math::numtheory](tcllib/files/modules/math/numtheory.md) Number Theory + + + [math::optimize](tcllib/files/modules/math/optimize.md) Optimisation routines + + + [math::PCA](tcllib/files/modules/math/pca.md) Package for Principal Component Analysis + + + [math::polynomials](tcllib/files/modules/math/polynomials.md) Polynomial functions + + + [math::rationalfunctions](tcllib/files/modules/math/rational_funcs.md) Polynomial functions + + + [math::roman](tcllib/files/modules/math/roman.md) Tools for creating and manipulating roman numerals + + + [math::special](tcllib/files/modules/math/special.md) Special mathematical functions + + + [math::statistics](tcllib/files/modules/math/statistics.md) Basic statistical functions and procedures + + + [math::trig](tcllib/files/modules/math/trig.md) Trigonometric anf hyperbolic functions + + + [simulation::annealing](tcllib/files/modules/simulation/annealing.md) Simulated annealing + + + [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md) Monte Carlo simulations + + + [simulation::random](tcllib/files/modules/simulation/simulation_random.md) Pseudo-random number generators + + * [Networking]() + + + [asn](tcllib/files/modules/asn/asn.md) ASN.1 BER encoder/decoder + + + [autoproxy](tcllib/files/modules/http/autoproxy.md) Automatic HTTP proxy usage and authentication + + + [bee](tcllib/files/modules/bee/bee.md) BitTorrent Serialization Format Encoder/Decoder + + + [dns](tcllib/files/modules/dns/tcllib_dns.md) Tcl Domain Name Service Client + + + [ftp](tcllib/files/modules/ftp/ftp.md) Client-side tcl implementation of the ftp protocol + + + [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) Uri handler for ftp urls + + + [ftpd](tcllib/files/modules/ftpd/ftpd.md) Tcl FTP server implementation + + + [ident](tcllib/files/modules/ident/ident.md) Ident protocol client + + + [irc](tcllib/files/modules/irc/irc.md) Create IRC connection and interface. + + + [ldap](tcllib/files/modules/ldap/ldap.md) LDAP client + + + [ldapx](tcllib/files/modules/ldap/ldapx.md) LDAP extended object interface + + + [nameserv](tcllib/files/modules/nns/nns_client.md) Name service facility, Client + + + [nameserv::auto](tcllib/files/modules/nns/nns_auto.md) Name service facility, Client Extension + + + [nameserv::common](tcllib/files/modules/nns/nns_common.md) Name service facility, shared definitions + + + [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md) Name service facility, client/server protocol + + + [nameserv::server](tcllib/files/modules/nns/nns_server.md) Name service facility, Server + + + [nmea](tcllib/files/modules/nmea/nmea.md) Process NMEA data + + + [nns](tcllib/files/apps/nns.md) Name service facility, Commandline Client Application + + + [nns_intro](tcllib/files/modules/nns/nns_intro.md) Name service facility, introduction + + + [nnsd](tcllib/files/apps/nnsd.md) Name service facility, Commandline Server Application + + + [nnslog](tcllib/files/apps/nnslog.md) Name service facility, Commandline Logging Client Application + + + [nntp](tcllib/files/modules/nntp/nntp.md) Tcl client for the NNTP protocol + + + [ntp_time](tcllib/files/modules/ntp/ntp_time.md) Tcl Time Service Client + + + [oauth](tcllib/files/modules/oauth/oauth.md) oauth API base signature + + + [picoirc](tcllib/files/modules/irc/picoirc.md) Small and simple embeddable IRC client. + + + [pop3](tcllib/files/modules/pop3/pop3.md) Tcl client for POP3 email protocol + + + [pop3d](tcllib/files/modules/pop3d/pop3d.md) Tcl POP3 server implementation + + + [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) Simple mailbox database for pop3d + + + [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md) Simple user database for pop3d + + + [S3](tcllib/files/modules/amazon-s3/S3.md) Amazon S3 Web Service Interface + + + [SASL](tcllib/files/modules/sasl/sasl.md) Implementation of SASL mechanisms for Tcl + + + [SASL::NTLM](tcllib/files/modules/sasl/ntlm.md) Implementation of SASL NTLM mechanism for Tcl + + + [SASL::SCRAM](tcllib/files/modules/sasl/scram.md) Implementation of SASL SCRAM mechanism for Tcl + + + [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md) Implementation of SASL NTLM mechanism for Tcl + + + [smtp](tcllib/files/modules/mime/smtp.md) Client-side tcl implementation of the smtp protocol + + + [smtpd](tcllib/files/modules/smtpd/smtpd.md) Tcl SMTP server implementation + + + [tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md) IPv4 and IPv6 address manipulation + + + [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 + + + [websocket](tcllib/files/modules/websocket/websocket.md) Tcl implementation of the websocket protocol + + * [Page Parser Generator]() + + + [page](tcllib/files/apps/page.md) Parser Generator + + + [page_intro](tcllib/files/modules/page/page_intro.md) page introduction + + + [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) page plugin manager + + + [page_util_flow](tcllib/files/modules/page/page_util_flow.md) page dataflow/treewalker utility + + + [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) page AST normalization, LEMON + + + [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) page AST normalization, PEG + + + [page_util_peg](tcllib/files/modules/page/page_util_peg.md) page PEG transformation utilities + + + [page_util_quote](tcllib/files/modules/page/page_util_quote.md) page character quoting utilities + + * [Parsing and Grammars]() + + + [pt](tcllib/files/apps/pt.md) Parser Tools Application + + + [pt::ast](tcllib/files/modules/pt/pt_astree.md) Abstract Syntax Tree Serialization + + + [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) C/PARAM, Canned configuration, Critcl + + + [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) C/PARAM, Canned configuration, TEA + + + [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) The JSON Grammar Exchange Format + + + [pt::param](tcllib/files/modules/pt/pt_param.md) PackRat Machine Specification + + + [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) Parsing Expression Serialization + + + [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) Parsing Expression Utilities + + + [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) Parsing Expression Grammar Serialization + + + [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) PEG Storage + + + [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) PEG Storage. Canned PEG grammar specification + + + [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) PEG Export + + + [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) PEG Export Plugin. Write CONTAINER format + + + [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) PEG Export Plugin. Write JSON format + + + [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) PEG Export Plugin. Write PEG format + + + [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) PEG Conversion. From CONTAINER format + + + [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) PEG Conversion. Read JSON format + + + [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) PEG Conversion. Read PEG format + + + [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) PEG Import + + + [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) PEG Import Plugin. From CONTAINER format + + + [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) PEG Import Plugin. Read JSON format + + + [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) PEG Import Plugin. Read PEG format + + + [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) Interpreter for parsing expression grammars + + + [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) PEG Conversion. Write CONTAINER format + + + [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) PEG Conversion. Write CPARAM format + + + [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) PEG Conversion. Write JSON format + + + [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) PEG Conversion. Write PARAM format + + + [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) PEG Conversion. Write PEG format + + + [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) PEG Conversion. Write TCLPARAM format + + + [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) PEG Language Tutorial + + + [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) Introduction to Parsing Expression Grammars + + + [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) Parser Generator + + + [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) Parsing Runtime Support, PARAM based + + + [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) Tcl/PARAM, Canned configuration, NX + + + [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) Tcl/PARAM, Canned configuration, Snit + + + [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) Tcl/PARAM, Canned configuration, Tcloo + + + [pt::util](tcllib/files/modules/pt/pt_util.md) General utilities + + + [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) Parser Tools Export API + + + [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) Parser Tools Import API + + + [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) Introduction to Parser Tools + + + [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) Parser Tools PEG Parser + + + [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) Parser API + + + [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md) Parser Tools PE Grammar Utility Operations + + * [Procedures, arguments, parameters, options]() + + + [tepam](tcllib/files/modules/tepam/tepam_introduction.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager + + + [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md) TEPAM procedure, reference manual + + * [Programming tools]() + + + [cmdline](tcllib/files/modules/cmdline/cmdline.md) Procedures to process command lines and options. + + + [comm](tcllib/files/modules/comm/comm.md) A remote communication facility for Tcl (8.3 and later) + + + [comm_wire](tcllib/files/modules/comm/comm_wire.md) The comm wire protocol + + + [control](tcllib/files/modules/control/control.md) Procedures for control flow structures. + + + [deleg_method](tcllib/files/modules/interp/deleg_method.md) Creation of comm delegates (snit methods) + + + [deleg_proc](tcllib/files/modules/interp/deleg_proc.md) Creation of comm delegates (procedures) + + + [fileutil](tcllib/files/modules/fileutil/fileutil.md) Procedures implementing some file utilities + + + [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) Generator core for compiler of magic(5) files + + + [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) Generator core for compiler of magic(5) files + + + [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) Procedures implementing file-type recognition + + + [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) Runtime core for file type recognition engines written in pure Tcl + + + [fileutil::multi](tcllib/files/modules/fileutil/multi.md) Multi-file operation, scatter/gather, standard object + + + [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md) Multi-file operation, scatter/gather + + + [fileutil_traverse](tcllib/files/modules/fileutil/traverse.md) Iterative directory traversal + + + [hook](tcllib/files/modules/hook/hook.md) Hooks + + + [interp](tcllib/files/modules/interp/tcllib_interp.md) Interp creation and aliasing + + + [log](tcllib/files/modules/log/log.md) Procedures to log messages of libraries and applications. + + + [logger](tcllib/files/modules/log/logger.md) System to control logging of events. + + + [logger::appender](tcllib/files/modules/log/loggerAppender.md) Collection of predefined appenders for logger + + + [logger::utils](tcllib/files/modules/log/loggerUtils.md) Utilities for logger + + + [multiplexer](tcllib/files/modules/multiplexer/multiplexer.md) One-to-many communication with sockets. + + + [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr.md) Manage a plugin + + + [profiler](tcllib/files/modules/profiler/profiler.md) Tcl source code profiler + + + [snit](tcllib/files/modules/snit/snit.md) Snit's Not Incr Tcl + + + [snitfaq](tcllib/files/modules/snit/snitfaq.md) Snit Frequently Asked Questions + + + [stooop](tcllib/files/modules/stooop/stooop.md) Object oriented extension. + + + [switched](tcllib/files/modules/stooop/switched.md) switch/option management. + + + [tie](tcllib/files/modules/tie/tie.md) Array persistence + + + [tie](tcllib/files/modules/tie/tie_std.md) Array persistence, standard data sources + + + [uevent](tcllib/files/modules/uev/uevent.md) User events + + + [wip](tcllib/files/modules/wip/wip.md) Word Interpreter + + * [System]() + + + [cron](tcllib/files/modules/cron/cron.md) Tool for automating the period callback of commands + + + [nettool](tcllib/files/modules/nettool/nettool.md) Tools for networked applications + + + [processman](tcllib/files/modules/processman/processman.md) Tool for automating the period callback of commands + + * [TclOO]() + + + [oometa](tcllib/files/modules/oometa/oometa.md) oo::meta A data registry for classess + + + [practcl](tcllib/files/modules/practcl/practcl.md) The Practcl Module + + + [tool](tcllib/files/modules/tool/tool.md) TclOO Library (TOOL) Framework + + * [Terminal control]() + + + [term](tcllib/files/modules/term/term.md) General terminal control + + + [term::ansi::code](tcllib/files/modules/term/ansi_code.md) Helper for control sequences + + + [term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) ANSI attribute sequences + + + [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) ANSI control sequences + + + [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) Macro sequences + + + [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md) Control operations and queries + + + [term::ansi::send](tcllib/files/modules/term/ansi_send.md) Output of ANSI control sequences to terminals + + + [term::interact::menu](tcllib/files/modules/term/imenu.md) Terminal widget, menu + + + [term::interact::pager](tcllib/files/modules/term/ipager.md) Terminal widget, paging + + + [term::receive](tcllib/files/modules/term/receive.md) General input from terminals + + + [term::receive::bind](tcllib/files/modules/term/term_bind.md) Keyboard dispatch from terminals + + + [term::send](tcllib/files/modules/term/term_send.md) General output to terminals + + * [Text formatter plugin]() + + + [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) docidx export plugin + + + [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) HTML export plugin + + + [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) JSON export plugin + + + [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) nroff export plugin + + + [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) plain text export plugin + + + [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) wiki export plugin + + + [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) docidx import plugin + + + [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) JSON import plugin + + + [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) doctoc export plugin + + + [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) HTML export plugin + + + [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) JSON export plugin + + + [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) nroff export plugin + + + [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) plain text export plugin + + + [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) wiki export plugin + + + [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) doctoc import plugin + + + [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) JSON import plugin + + * [Text processing]() + + + [ascii85](tcllib/files/modules/base64/ascii85.md) ascii85-encode/decode binary data + + + [base32](tcllib/files/modules/base32/base32.md) base32 standard encoding + + + [base32::core](tcllib/files/modules/base32/base32core.md) Expanding basic base32 maps + + + [base32::hex](tcllib/files/modules/base32/base32hex.md) base32 extended hex encoding + + + [base64](tcllib/files/modules/base64/base64.md) base64-encode/decode binary data + + + [bibtex](tcllib/files/modules/bibtex/bibtex.md) Parse bibtex files + + + [clock_iso8601](tcllib/files/modules/clock/iso8601.md) Parsing ISO 8601 dates/times + + + [clock_rfc2822](tcllib/files/modules/clock/rfc2822.md) Parsing ISO 8601 dates/times + + + [csv](tcllib/files/modules/csv/csv.md) Procedures to handle CSV data. + + + [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) Procedures to parse HTML strings + + + [inifile](tcllib/files/modules/inifile/ini.md) Parsing of Windows INI files + + + [markdown](tcllib/files/modules/markdown/markdown.md) Converts Markdown text to HTML + + + [mime](tcllib/files/modules/mime/mime.md) Manipulation of MIME body parts + + + [rcs](tcllib/files/modules/rcs/rcs.md) RCS low level utilities + + + [string::token](tcllib/files/modules/string/token.md) Regex based iterative lexing + + + [string::token::shell](tcllib/files/modules/string/token_shell.md) Parsing of shell command line + + + [textutil](tcllib/files/modules/textutil/textutil.md) Procedures to manipulate texts and strings. + + + [textutil::adjust](tcllib/files/modules/textutil/adjust.md) Procedures to adjust, indent, and undent paragraphs + + + [textutil::repeat](tcllib/files/modules/textutil/repeat.md) Procedures to repeat strings. + + + [textutil::split](tcllib/files/modules/textutil/textutil_split.md) Procedures to split texts + + + [textutil::string](tcllib/files/modules/textutil/textutil_string.md) Procedures to manipulate texts and strings. + + + [textutil::tabify](tcllib/files/modules/textutil/tabify.md) Procedures to (un)tabify strings + + + [textutil::trim](tcllib/files/modules/textutil/trim.md) Procedures to trim strings + + + [uuencode](tcllib/files/modules/base64/uuencode.md) UU-encode/decode binary data + + + [xsxp](tcllib/files/modules/amazon-s3/xsxp.md) eXtremely Simple Xml Parser + + + [yencode](tcllib/files/modules/base64/yencode.md) Y-encode/decode binary data + + * [Transfer module]() + + + [transfer::connect](tcllib/files/modules/transfer/connect.md) Connection setup + + + [transfer::copy](tcllib/files/modules/transfer/copyops.md) Data transfer foundation + + + [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) Queued transfers + + + [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) Data destination + + + [transfer::data::source](tcllib/files/modules/transfer/dsource.md) Data source + + + [transfer::receiver](tcllib/files/modules/transfer/receiver.md) Data source + + + [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md) Data source + + * [Unfiled]() + + + [cache::async](tcllib/files/modules/cache/async.md) Asynchronous in-memory cache + + + [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 + + + [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) Accessing a server providing tiles for slippy-based maps + + + [mapproj](tcllib/files/modules/mapproj/mapproj.md) Map projection routines + + + [math::calculus::symdiff](tcllib/files/modules/math/symdiff.md) Symbolic differentiation for Tcl + + + [namespacex](tcllib/files/modules/namespacex/namespacex.md) Namespace utility commands + + + [rest](tcllib/files/modules/rest/rest.md) define REST web APIs and call them inline or asychronously + + + [stringprep](tcllib/files/modules/stringprep/stringprep.md) Implementation of stringprep + + + [stringprep::data](tcllib/files/modules/stringprep/stringprep_data.md) stringprep data tables, generated, internal + + + [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 + + + [unicode](tcllib/files/modules/stringprep/unicode.md) Implementation of Unicode normalization + + + [unicode::data](tcllib/files/modules/stringprep/unicode_data.md) unicode data tables, generated, internal + + + [units](tcllib/files/modules/units/units.md) unit conversion + + + [yaml](tcllib/files/modules/yaml/yaml.md) YAML Format Encoder/Decoder + + * [Utilities]() + + + [dicttool](tcllib/files/modules/dicttool/dicttool.md) Dictionary Tools + + * [Utility]() + + + [defer](tcllib/files/modules/defer/defer.md) Defered execution + + + [lambda](tcllib/files/modules/lambda/lambda.md) Utility commands for anonymous procedures + + + [lazyset](tcllib/files/modules/lazyset/lazyset.md) Lazy evaluation + + + [oo::util](tcllib/files/modules/ooutil/ooutil.md) Utility commands for TclOO + + + [oo::util](tcllib/files/modules/tool/meta.md) Utility commands for TclOO + + + [throw](tcllib/files/modules/try/tcllib_throw.md) throw - Throw an error exception with a message + + + [tool::dict_ensemble](tcllib/files/modules/tool/tool_dict_ensemble.md) Dictionary Tools + + + [try](tcllib/files/modules/try/tcllib_try.md) try - Trap and process errors and exceptions + + * [Validation, Type checking]() + + + [valtype::common](tcllib/files/modules/valtype/valtype_common.md) Validation, common code + + + [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) Validation for AMEX creditcard number + + + [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) Validation for Discover creditcard number + + + [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) Validation for Mastercard creditcard number + + + [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) Validation for VISA creditcard number + + + [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) Validation for EAN13 + + + [valtype::iban](tcllib/files/modules/valtype/iban.md) Validation for IBAN + + + [valtype::imei](tcllib/files/modules/valtype/imei.md) Validation for IMEI + + + [valtype::isbn](tcllib/files/modules/valtype/isbn.md) Validation for ISBN + + + [valtype::luhn](tcllib/files/modules/valtype/luhn.md) Validation for plain number with a LUHN checkdigit + + + [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) Validation for plain number with a LUHN5 checkdigit + + + [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) Validation for USNPI + + + [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md) Validation for plain number with a VERHOEFF checkdigit + + - [By Type]() + + * [Applications]() + + + [dtplite](tcllib/files/apps/dtplite.md) Lightweight DocTools Markup Processor + + + [nns](tcllib/files/apps/nns.md) Name service facility, Commandline Client Application + + + [nnsd](tcllib/files/apps/nnsd.md) Name service facility, Commandline Server Application + + + [nnslog](tcllib/files/apps/nnslog.md) Name service facility, Commandline Logging Client Application + + + [page](tcllib/files/apps/page.md) Parser Generator + + + [pt](tcllib/files/apps/pt.md) Parser Tools Application + + + [tcldocstrip](tcllib/files/apps/tcldocstrip.md) Tcl-based Docstrip Processor + + * [Modules]() + + + [aes]() + + - [aes](tcllib/files/modules/aes/aes.md) Implementation of the AES block cipher + + + [amazon-s3]() + + - [S3](tcllib/files/modules/amazon-s3/S3.md) Amazon S3 Web Service Interface + + - [xsxp](tcllib/files/modules/amazon-s3/xsxp.md) eXtremely Simple Xml Parser + + + [asn]() + + - [asn](tcllib/files/modules/asn/asn.md) ASN.1 BER encoder/decoder + + + [base32]() + + - [base32](tcllib/files/modules/base32/base32.md) base32 standard encoding + + - [base32::core](tcllib/files/modules/base32/base32core.md) Expanding basic base32 maps + + - [base32::hex](tcllib/files/modules/base32/base32hex.md) base32 extended hex encoding + + + [base64]() + + - [ascii85](tcllib/files/modules/base64/ascii85.md) ascii85-encode/decode binary data + + - [base64](tcllib/files/modules/base64/base64.md) base64-encode/decode binary data + + - [uuencode](tcllib/files/modules/base64/uuencode.md) UU-encode/decode binary data + + - [yencode](tcllib/files/modules/base64/yencode.md) Y-encode/decode binary data + + + [bee]() + + - [bee](tcllib/files/modules/bee/bee.md) BitTorrent Serialization Format Encoder/Decoder + + + [bench]() + + - [bench](tcllib/files/modules/bench/bench.md) bench - Processing benchmark suites + + - [bench::in](tcllib/files/modules/bench/bench_read.md) bench::in - Reading benchmark results + + - [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) bench::out::csv - Formatting benchmark results as CSV + + - [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) bench::out::text - Formatting benchmark results as human readable text + + - [bench_intro](tcllib/files/modules/bench/bench_intro.md) bench introduction + + - [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) bench language introduction + + - [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md) bench language specification + + + [bibtex]() + + - [bibtex](tcllib/files/modules/bibtex/bibtex.md) Parse bibtex files + + + [blowfish]() + + - [blowfish](tcllib/files/modules/blowfish/blowfish.md) Implementation of the Blowfish block cipher + + + [cache]() + + - [cache::async](tcllib/files/modules/cache/async.md) Asynchronous in-memory cache + + + [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 + + + [cmdline]() + + - [cmdline](tcllib/files/modules/cmdline/cmdline.md) Procedures to process command lines and options. + + + [comm]() + + - [comm](tcllib/files/modules/comm/comm.md) A remote communication facility for Tcl (8.3 and later) + + - [comm_wire](tcllib/files/modules/comm/comm_wire.md) The comm wire protocol + + + [control]() + + - [control](tcllib/files/modules/control/control.md) Procedures for control flow structures. + + + [coroutine]() + + - [coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) Coroutine based event and IO handling + + - [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) Automatic event and IO coroutine awareness + + + [counter]() + + - [counter](tcllib/files/modules/counter/counter.md) Procedures for counters and histograms + + + [crc]() + + - [cksum](tcllib/files/modules/crc/cksum.md) Calculate a cksum(1) compatible checksum + + - [crc16](tcllib/files/modules/crc/crc16.md) Perform a 16bit Cyclic Redundancy Check + + - [crc32](tcllib/files/modules/crc/crc32.md) Perform a 32bit Cyclic Redundancy Check + + - [sum](tcllib/files/modules/crc/sum.md) Calculate a sum(1) compatible checksum + + + [cron]() + + - [cron](tcllib/files/modules/cron/cron.md) Tool for automating the period callback of commands + + + [csv]() + + - [csv](tcllib/files/modules/csv/csv.md) Procedures to handle CSV data. + + + [debug]() + + - [debug](tcllib/files/modules/debug/debug.md) debug narrative - core + + - [debug::caller](tcllib/files/modules/debug/debug_caller.md) debug narrative - caller + + - [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) debug narrative - heartbeat + + - [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md) debug narrative - timestamping + + + [defer]() + + - [defer](tcllib/files/modules/defer/defer.md) Defered execution + + + [des]() + + - [des](tcllib/files/modules/des/des.md) Implementation of the DES and triple-DES ciphers + + - [tclDES](tcllib/files/modules/des/tcldes.md) Implementation of the DES and triple-DES ciphers + + - [tclDESjr](tcllib/files/modules/des/tcldesjr.md) Implementation of the DES and triple-DES ciphers + + + [dicttool]() + + - [dicttool](tcllib/files/modules/dicttool/dicttool.md) Dictionary Tools + + + [dns]() + + - [dns](tcllib/files/modules/dns/tcllib_dns.md) Tcl Domain Name Service Client + + - [tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md) IPv4 and IPv6 address manipulation + + + [docstrip]() + + - [docstrip](tcllib/files/modules/docstrip/docstrip.md) Docstrip style source code extraction + + - [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) Docstrip-related utilities + + + [doctools]() + + - [docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) docidx introduction + + - [docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) docidx language command reference + + - [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) docidx language faq + + - [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) docidx language introduction + + - [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) docidx language syntax + + - [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) docidx plugin API reference + + - [doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) doctoc introduction + + - [doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) doctoc language command reference + + - [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) doctoc language faq + + - [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) doctoc language introduction + + - [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) doctoc language syntax + + - [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) doctoc plugin API reference + + - [doctools](tcllib/files/modules/doctools/doctools.md) doctools - Processing documents + + - [doctools::changelog](tcllib/files/modules/doctools/changelog.md) Processing text in Emacs ChangeLog format + + - [doctools::cvs](tcllib/files/modules/doctools/cvs.md) Processing text in 'cvs log' format + + - [doctools::idx](tcllib/files/modules/doctools/docidx.md) docidx - Processing indices + + - [doctools::toc](tcllib/files/modules/doctools/doctoc.md) doctoc - Processing tables of contents + + - [doctools_intro](tcllib/files/modules/doctools/doctools_intro.md) doctools introduction + + - [doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) doctools language command reference + + - [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) doctools language faq + + - [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) doctools language introduction + + - [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md) doctools language syntax + + - [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md) doctools plugin API reference + + - [mpexpand](tcllib/files/modules/doctools/mpexpand.md) Markup processor + + + [doctools2base]() + + - [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) Default CSS style for HTML export plugins + + - [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) Message catalog management for the various document parsers + + - [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) Default CSS style for NROFF export plugins + + - [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) Processing text in 'subst -novariables' format + + + [doctools2idx]() + + - [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) DocTools - Keyword indices + + - [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) Holding keyword indices + + - [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) Exporting keyword indices + + - [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) docidx export plugin + + - [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) HTML export plugin + + - [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) JSON export plugin + + - [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) nroff export plugin + + - [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) plain text export plugin + + - [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) wiki export plugin + + - [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) Importing keyword indices + + - [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) docidx import plugin + + - [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) JSON import plugin + + - [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) Parsing text in docidx format + + - [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) Docidx serialization utilities + + - [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) Message catalog for the docidx parser (C) + + - [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) Message catalog for the docidx parser (DE) + + - [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) Message catalog for the docidx parser (EN) + + - [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) Message catalog for the docidx parser (FR) + + + [doctools2toc]() + + - [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) DocTools - Tables of Contents + + - [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) Message catalog for the doctoc parser (C) + + - [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) Message catalog for the doctoc parser (DE) + + - [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) Message catalog for the doctoc parser (EN) + + - [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md) Message catalog for the doctoc parser (FR) + + - [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) Holding tables of contents + + - [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) Exporting tables of contents + + - [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) doctoc export plugin + + - [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) HTML export plugin + + - [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) JSON export plugin + + - [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) nroff export plugin + + - [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) plain text export plugin + + - [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) wiki export plugin + + - [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) Importing keyword indices + + - [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) doctoc import plugin + + - [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) JSON import plugin + + - [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) Parsing text in doctoc format + + - [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) Doctoc serialization utilities + + + [dtplite]() + + - [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) Lightweight DocTools Markup Processor + + + [fileutil]() + + - [fileutil](tcllib/files/modules/fileutil/fileutil.md) Procedures implementing some file utilities + + - [fileutil::multi](tcllib/files/modules/fileutil/multi.md) Multi-file operation, scatter/gather, standard object + + - [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md) Multi-file operation, scatter/gather + + - [fileutil_traverse](tcllib/files/modules/fileutil/traverse.md) Iterative directory traversal + + + [ftp]() + + - [ftp](tcllib/files/modules/ftp/ftp.md) Client-side tcl implementation of the ftp protocol + + - [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) Uri handler for ftp urls + + + [ftpd]() + + - [ftpd](tcllib/files/modules/ftpd/ftpd.md) Tcl FTP server implementation + + + [fumagic]() + + - [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) Generator core for compiler of magic(5) files + + - [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) Generator core for compiler of magic(5) files + + - [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) Procedures implementing file-type recognition + + - [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) Runtime core for file type recognition engines written in pure Tcl + + + [generator]() + + - [generator](tcllib/files/modules/generator/generator.md) Procedures for creating and using generators. + + + [gpx]() + + - [gpx](tcllib/files/modules/gpx/gpx.md) Extracts waypoints, tracks and routes from GPX files + + + [grammar_aycock]() + + - [grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) Aycock-Horspool-Earley parser generator for Tcl + + + [grammar_fa]() + + - [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) Create and manipulate finite automatons + + - [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) Create and use deterministic acceptors + + - [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) Execute deterministic finite automatons + + - [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) Operations on finite automatons + + + [grammar_me]() + + - [grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) Virtual machine implementation II for parsing token streams + + - [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) ME virtual machine state manipulation + + - [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) ME assembler + + - [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) Virtual machine implementation I for parsing token streams + + - [grammar::me::util](tcllib/files/modules/grammar_me/me_util.md) AST utilities + + - [grammar::me_ast](tcllib/files/modules/grammar_me/me_ast.md) Various representations of ASTs + + - [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) Introduction to virtual machines for parsing token streams + + - [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) Virtual machine for parsing token streams + + + [grammar_peg]() + + - [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) Create and manipulate parsing expression grammars + + - [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) Interpreter for parsing expression grammars + + + [hook]() + + - [hook](tcllib/files/modules/hook/hook.md) Hooks + + + [html]() + + - [html](tcllib/files/modules/html/html.md) Procedures to generate HTML structures + + + [htmlparse]() + + - [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) Procedures to parse HTML strings + + + [http]() + + - [autoproxy](tcllib/files/modules/http/autoproxy.md) Automatic HTTP proxy usage and authentication + + + [httpd]() + + - [tool](tcllib/files/modules/httpd/httpd.md) A TclOO and coroutine based web server + + + [ident]() + + - [ident](tcllib/files/modules/ident/ident.md) Ident protocol client + + + [imap4]() + + - [imap4](tcllib/files/modules/imap4/imap4.md) imap client-side tcl implementation of imap protocol + + + [inifile]() + + - [inifile](tcllib/files/modules/inifile/ini.md) Parsing of Windows INI files + + + [interp]() + + - [deleg_method](tcllib/files/modules/interp/deleg_method.md) Creation of comm delegates (snit methods) + + - [deleg_proc](tcllib/files/modules/interp/deleg_proc.md) Creation of comm delegates (procedures) + + - [interp](tcllib/files/modules/interp/tcllib_interp.md) Interp creation and aliasing + + + [irc]() + + - [irc](tcllib/files/modules/irc/irc.md) Create IRC connection and interface. + + - [picoirc](tcllib/files/modules/irc/picoirc.md) Small and simple embeddable IRC client. + + + [javascript]() + + - [javascript](tcllib/files/modules/javascript/javascript.md) Procedures to generate HTML and Java Script structures. + + + [jpeg]() + + - [jpeg](tcllib/files/modules/jpeg/jpeg.md) JPEG querying and manipulation of meta data + + + [json]() + + - [json](tcllib/files/modules/json/json.md) JSON parser + + - [json::write](tcllib/files/modules/json/json_write.md) JSON generation + + + [lambda]() + + - [lambda](tcllib/files/modules/lambda/lambda.md) Utility commands for anonymous procedures + + + [lazyset]() + + - [lazyset](tcllib/files/modules/lazyset/lazyset.md) Lazy evaluation + + + [ldap]() + + - [ldap](tcllib/files/modules/ldap/ldap.md) LDAP client + + - [ldapx](tcllib/files/modules/ldap/ldapx.md) LDAP extended object interface + + + [log]() + + - [log](tcllib/files/modules/log/log.md) Procedures to log messages of libraries and applications. + + - [logger](tcllib/files/modules/log/logger.md) System to control logging of events. + + - [logger::appender](tcllib/files/modules/log/loggerAppender.md) Collection of predefined appenders for logger + + - [logger::utils](tcllib/files/modules/log/loggerUtils.md) Utilities for logger + + + [map]() + + - [map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) Resolving geographical names with a Nominatim service + + - [map::slippy](tcllib/files/modules/map/map_slippy.md) Common code for slippy based map packages + + - [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) Management of a tile cache in the local filesystem + + - [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) Accessing a server providing tiles for slippy-based maps + + + [mapproj]() + + - [mapproj](tcllib/files/modules/mapproj/mapproj.md) Map projection routines + + + [markdown]() + + - [markdown](tcllib/files/modules/markdown/markdown.md) Converts Markdown text to HTML + + + [math]() + + - [math](tcllib/files/modules/math/math.md) Tcl Math Library + + - [math::bigfloat](tcllib/files/modules/math/bigfloat.md) Arbitrary precision floating-point numbers + + - [math::bignum](tcllib/files/modules/math/bignum.md) Arbitrary precision integer numbers + + - [math::calculus](tcllib/files/modules/math/calculus.md) Integration and ordinary differential equations + + - [math::calculus::romberg](tcllib/files/modules/math/romberg.md) Romberg integration + + - [math::calculus::symdiff](tcllib/files/modules/math/symdiff.md) Symbolic differentiation for Tcl + + - [math::combinatorics](tcllib/files/modules/math/combinatorics.md) Combinatorial functions in the Tcl Math Library + + - [math::complexnumbers](tcllib/files/modules/math/qcomplex.md) Straightforward complex number package + + - [math::constants](tcllib/files/modules/math/constants.md) Mathematical and numerical constants + + - [math::decimal](tcllib/files/modules/math/decimal.md) General decimal arithmetic + + - [math::exact](tcllib/files/modules/math/exact.md) Exact Real Arithmetic + + - [math::fourier](tcllib/files/modules/math/fourier.md) Discrete and fast fourier transforms + + - [math::fuzzy](tcllib/files/modules/math/fuzzy.md) Fuzzy comparison of floating-point numbers + + - [math::geometry](tcllib/files/modules/math/math_geometry.md) Geometrical computations + + - [math::interpolate](tcllib/files/modules/math/interpolate.md) Interpolation routines + + - [math::linearalgebra](tcllib/files/modules/math/linalg.md) Linear Algebra + + - [math::numtheory](tcllib/files/modules/math/numtheory.md) Number Theory + + - [math::optimize](tcllib/files/modules/math/optimize.md) Optimisation routines + + - [math::PCA](tcllib/files/modules/math/pca.md) Package for Principal Component Analysis + + - [math::polynomials](tcllib/files/modules/math/polynomials.md) Polynomial functions + + - [math::rationalfunctions](tcllib/files/modules/math/rational_funcs.md) Polynomial functions + + - [math::roman](tcllib/files/modules/math/roman.md) Tools for creating and manipulating roman numerals + + - [math::special](tcllib/files/modules/math/special.md) Special mathematical functions + + - [math::statistics](tcllib/files/modules/math/statistics.md) Basic statistical functions and procedures + + - [math::trig](tcllib/files/modules/math/trig.md) Trigonometric anf hyperbolic functions + + - [tclrep/machineparameters](tcllib/files/modules/math/machineparameters.md) Compute double precision machine parameters. + + + [md4]() + + - [md4](tcllib/files/modules/md4/md4.md) MD4 Message-Digest Algorithm + + + [md5]() + + - [md5](tcllib/files/modules/md5/md5.md) MD5 Message-Digest Algorithm + + + [md5crypt]() + + - [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) MD5-based password encryption + + + [mime]() + + - [mime](tcllib/files/modules/mime/mime.md) Manipulation of MIME body parts + + - [smtp](tcllib/files/modules/mime/smtp.md) Client-side tcl implementation of the smtp protocol + + + [multiplexer]() + + - [multiplexer](tcllib/files/modules/multiplexer/multiplexer.md) One-to-many communication with sockets. + + + [namespacex]() + + - [namespacex](tcllib/files/modules/namespacex/namespacex.md) Namespace utility commands + + + [ncgi]() + + - [ncgi](tcllib/files/modules/ncgi/ncgi.md) Procedures to manipulate CGI values. + + + [nettool]() + + - [nettool](tcllib/files/modules/nettool/nettool.md) Tools for networked applications + + + [nmea]() + + - [nmea](tcllib/files/modules/nmea/nmea.md) Process NMEA data + + + [nns]() + + - [nameserv](tcllib/files/modules/nns/nns_client.md) Name service facility, Client + + - [nameserv::auto](tcllib/files/modules/nns/nns_auto.md) Name service facility, Client Extension + + - [nameserv::common](tcllib/files/modules/nns/nns_common.md) Name service facility, shared definitions + + - [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md) Name service facility, client/server protocol + + - [nameserv::server](tcllib/files/modules/nns/nns_server.md) Name service facility, Server + + - [nns_intro](tcllib/files/modules/nns/nns_intro.md) Name service facility, introduction + + + [nntp]() + + - [nntp](tcllib/files/modules/nntp/nntp.md) Tcl client for the NNTP protocol + + + [ntp]() + + - [ntp_time](tcllib/files/modules/ntp/ntp_time.md) Tcl Time Service Client + + + [oauth]() + + - [oauth](tcllib/files/modules/oauth/oauth.md) oauth API base signature + + + [oometa]() + + - [oometa](tcllib/files/modules/oometa/oometa.md) oo::meta A data registry for classess + + + [ooutil]() + + - [oo::util](tcllib/files/modules/ooutil/ooutil.md) Utility commands for TclOO + + + [otp]() + + - [otp](tcllib/files/modules/otp/otp.md) One-Time Passwords + + + [page]() + + - [page_intro](tcllib/files/modules/page/page_intro.md) page introduction + + - [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) page plugin manager + + - [page_util_flow](tcllib/files/modules/page/page_util_flow.md) page dataflow/treewalker utility + + - [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) page AST normalization, LEMON + + - [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) page AST normalization, PEG + + - [page_util_peg](tcllib/files/modules/page/page_util_peg.md) page PEG transformation utilities + + - [page_util_quote](tcllib/files/modules/page/page_util_quote.md) page character quoting utilities + + + [pki]() + + - [pki](tcllib/files/modules/pki/pki.md) Implementation of the public key cipher + + + [pluginmgr]() + + - [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr.md) Manage a plugin + + + [png]() + + - [png](tcllib/files/modules/png/png.md) PNG querying and manipulation of meta data + + + [pop3]() + + - [pop3](tcllib/files/modules/pop3/pop3.md) Tcl client for POP3 email protocol + + + [pop3d]() + + - [pop3d](tcllib/files/modules/pop3d/pop3d.md) Tcl POP3 server implementation + + - [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) Simple mailbox database for pop3d + + - [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md) Simple user database for pop3d + + + [practcl]() + + - [practcl](tcllib/files/modules/practcl/practcl.md) The Practcl Module + + + [processman]() + + - [processman](tcllib/files/modules/processman/processman.md) Tool for automating the period callback of commands + + + [profiler]() + + - [profiler](tcllib/files/modules/profiler/profiler.md) Tcl source code profiler + + + [pt]() + + - [pt::ast](tcllib/files/modules/pt/pt_astree.md) Abstract Syntax Tree Serialization + + - [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) C/PARAM, Canned configuration, Critcl + + - [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) C/PARAM, Canned configuration, TEA + + - [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) The JSON Grammar Exchange Format + + - [pt::param](tcllib/files/modules/pt/pt_param.md) PackRat Machine Specification + + - [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) Parsing Expression Serialization + + - [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) Parsing Expression Utilities + + - [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) Parsing Expression Grammar Serialization + + - [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) PEG Storage + + - [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) PEG Storage. Canned PEG grammar specification + + - [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) PEG Export + + - [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) PEG Export Plugin. Write CONTAINER format + + - [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) PEG Export Plugin. Write JSON format + + - [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) PEG Export Plugin. Write PEG format + + - [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) PEG Conversion. From CONTAINER format + + - [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) PEG Conversion. Read JSON format + + - [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) PEG Conversion. Read PEG format + + - [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) PEG Import + + - [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) PEG Import Plugin. From CONTAINER format + + - [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) PEG Import Plugin. Read JSON format + + - [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) PEG Import Plugin. Read PEG format + + - [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) Interpreter for parsing expression grammars + + - [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) PEG Conversion. Write CONTAINER format + + - [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) PEG Conversion. Write CPARAM format + + - [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) PEG Conversion. Write JSON format + + - [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) PEG Conversion. Write PARAM format + + - [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) PEG Conversion. Write PEG format + + - [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) PEG Conversion. Write TCLPARAM format + + - [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) PEG Language Tutorial + + - [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) Introduction to Parsing Expression Grammars + + - [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) Parser Generator + + - [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) Parsing Runtime Support, PARAM based + + - [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) Tcl/PARAM, Canned configuration, NX + + - [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) Tcl/PARAM, Canned configuration, Snit + + - [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) Tcl/PARAM, Canned configuration, Tcloo + + - [pt::util](tcllib/files/modules/pt/pt_util.md) General utilities + + - [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) Parser Tools Export API + + - [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) Parser Tools Import API + + - [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) Introduction to Parser Tools + + - [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) Parser Tools PEG Parser + + - [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) Parser API + + - [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md) Parser Tools PE Grammar Utility Operations + + + [rc4]() + + - [rc4](tcllib/files/modules/rc4/rc4.md) Implementation of the RC4 stream cipher + + + [rcs]() + + - [rcs](tcllib/files/modules/rcs/rcs.md) RCS low level utilities + + + [report]() + + - [report](tcllib/files/modules/report/report.md) Create and manipulate report objects + + + [rest]() + + - [rest](tcllib/files/modules/rest/rest.md) define REST web APIs and call them inline or asychronously + + + [ripemd]() + + - [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) RIPEMD-128 Message-Digest Algorithm + + - [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) RIPEMD-160 Message-Digest Algorithm + + + [sasl]() + + - [SASL](tcllib/files/modules/sasl/sasl.md) Implementation of SASL mechanisms for Tcl + + - [SASL::NTLM](tcllib/files/modules/sasl/ntlm.md) Implementation of SASL NTLM mechanism for Tcl + + - [SASL::SCRAM](tcllib/files/modules/sasl/scram.md) Implementation of SASL SCRAM mechanism for Tcl + + - [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md) Implementation of SASL NTLM mechanism for Tcl + + + [sha1]() + + - [sha1](tcllib/files/modules/sha1/sha1.md) SHA1 Message-Digest Algorithm + + - [sha256](tcllib/files/modules/sha1/sha256.md) SHA256 Message-Digest Algorithm + + + [simulation]() + + - [simulation::annealing](tcllib/files/modules/simulation/annealing.md) Simulated annealing + + - [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md) Monte Carlo simulations + + - [simulation::random](tcllib/files/modules/simulation/simulation_random.md) Pseudo-random number generators + + + [smtpd]() + + - [smtpd](tcllib/files/modules/smtpd/smtpd.md) Tcl SMTP server implementation + + + [snit]() + + - [snit](tcllib/files/modules/snit/snit.md) Snit's Not Incr Tcl + + - [snitfaq](tcllib/files/modules/snit/snitfaq.md) Snit Frequently Asked Questions + + + [soundex]() + + - [soundex](tcllib/files/modules/soundex/soundex.md) Soundex + + + [stooop]() + + - [stooop](tcllib/files/modules/stooop/stooop.md) Object oriented extension. + + - [switched](tcllib/files/modules/stooop/switched.md) switch/option management. + + + [string]() + + - [string::token](tcllib/files/modules/string/token.md) Regex based iterative lexing + + - [string::token::shell](tcllib/files/modules/string/token_shell.md) Parsing of shell command line + + + [stringprep]() + + - [stringprep](tcllib/files/modules/stringprep/stringprep.md) Implementation of stringprep + + - [stringprep::data](tcllib/files/modules/stringprep/stringprep_data.md) stringprep data tables, generated, internal + + - [unicode](tcllib/files/modules/stringprep/unicode.md) Implementation of Unicode normalization + + - [unicode::data](tcllib/files/modules/stringprep/unicode_data.md) unicode data tables, generated, internal + + + [struct]() + + - [struct::disjointset](tcllib/files/modules/struct/disjointset.md) Disjoint set data structure + + - [struct::graph](tcllib/files/modules/struct/graph.md) Create and manipulate directed graph objects + + - [struct::graph::op](tcllib/files/modules/struct/graphops.md) Operation for (un)directed graph objects + + - [struct::graph_v1](tcllib/files/modules/struct/graph1.md) Create and manipulate directed graph objects + + - [struct::list](tcllib/files/modules/struct/struct_list.md) Procedures for manipulating lists + + - [struct::matrix](tcllib/files/modules/struct/matrix.md) Create and manipulate matrix objects + + - [struct::matrix_v1](tcllib/files/modules/struct/matrix1.md) Create and manipulate matrix objects + + - [struct::pool](tcllib/files/modules/struct/pool.md) Create and manipulate pool objects (of discrete items) + + - [struct::prioqueue](tcllib/files/modules/struct/prioqueue.md) Create and manipulate prioqueue objects + + - [struct::queue](tcllib/files/modules/struct/queue.md) Create and manipulate queue objects + + - [struct::record](tcllib/files/modules/struct/record.md) Define and create records (similar to 'C' structures) + + - [struct::set](tcllib/files/modules/struct/struct_set.md) Procedures for manipulating sets + + - [struct::skiplist](tcllib/files/modules/struct/skiplist.md) Create and manipulate skiplists + + - [struct::stack](tcllib/files/modules/struct/stack.md) Create and manipulate stack objects + + - [struct::tree](tcllib/files/modules/struct/struct_tree.md) Create and manipulate tree objects + + - [struct::tree_v1](tcllib/files/modules/struct/struct_tree1.md) Create and manipulate tree objects + + + [tar]() + + - [tar](tcllib/files/modules/tar/tar.md) Tar file creation, extraction & manipulation + + + [tepam]() + + - [tepam](tcllib/files/modules/tepam/tepam_introduction.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager + + - [tepam::argument_dialogbox](tcllib/files/modules/tepam/tepam_argument_dialogbox.md) TEPAM argument_dialogbox, reference manual + + - [tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md) TEPAM DOC Generation, reference manual + + - [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md) TEPAM procedure, reference manual + + + [term]() + + - [term](tcllib/files/modules/term/term.md) General terminal control + + - [term::ansi::code](tcllib/files/modules/term/ansi_code.md) Helper for control sequences + + - [term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) ANSI attribute sequences + + - [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) ANSI control sequences + + - [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) Macro sequences + + - [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md) Control operations and queries + + - [term::ansi::send](tcllib/files/modules/term/ansi_send.md) Output of ANSI control sequences to terminals + + - [term::interact::menu](tcllib/files/modules/term/imenu.md) Terminal widget, menu + + - [term::interact::pager](tcllib/files/modules/term/ipager.md) Terminal widget, paging + + - [term::receive](tcllib/files/modules/term/receive.md) General input from terminals + + - [term::receive::bind](tcllib/files/modules/term/term_bind.md) Keyboard dispatch from terminals + + - [term::send](tcllib/files/modules/term/term_send.md) General output to terminals + + + [textutil]() + + - [textutil](tcllib/files/modules/textutil/textutil.md) Procedures to manipulate texts and strings. + + - [textutil::adjust](tcllib/files/modules/textutil/adjust.md) Procedures to adjust, indent, and undent paragraphs + + - [textutil::expander](tcllib/files/modules/textutil/expander.md) Procedures to process templates and expand text. + + - [textutil::repeat](tcllib/files/modules/textutil/repeat.md) Procedures to repeat strings. + + - [textutil::split](tcllib/files/modules/textutil/textutil_split.md) Procedures to split texts + + - [textutil::string](tcllib/files/modules/textutil/textutil_string.md) Procedures to manipulate texts and strings. + + - [textutil::tabify](tcllib/files/modules/textutil/tabify.md) Procedures to (un)tabify strings + + - [textutil::trim](tcllib/files/modules/textutil/trim.md) Procedures to trim strings + + + [tie]() + + - [tie](tcllib/files/modules/tie/tie.md) Array persistence + + - [tie](tcllib/files/modules/tie/tie_std.md) Array persistence, standard data sources + + + [tiff]() + + - [tiff](tcllib/files/modules/tiff/tiff.md) TIFF reading, writing, and querying and manipulation of meta data + + + [tool]() + + - [oo::util](tcllib/files/modules/tool/meta.md) Utility commands for TclOO + + - [tool](tcllib/files/modules/tool/tool.md) TclOO Library (TOOL) Framework + + - [tool::dict_ensemble](tcllib/files/modules/tool/tool_dict_ensemble.md) Dictionary Tools + + + [transfer]() + + - [transfer::connect](tcllib/files/modules/transfer/connect.md) Connection setup + + - [transfer::copy](tcllib/files/modules/transfer/copyops.md) Data transfer foundation + + - [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) Queued transfers + + - [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) Data destination + + - [transfer::data::source](tcllib/files/modules/transfer/dsource.md) Data source + + - [transfer::receiver](tcllib/files/modules/transfer/receiver.md) Data source + + - [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md) Data source + + + [treeql]() + + - [treeql](tcllib/files/modules/treeql/treeql.md) Query tree objects + + + [try]() + + - [throw](tcllib/files/modules/try/tcllib_throw.md) throw - Throw an error exception with a message + + - [try](tcllib/files/modules/try/tcllib_try.md) try - Trap and process errors and exceptions + + + [udpcluster]() + + - [udpcluster](tcllib/files/modules/udpcluster/udpcluster.md) UDP Peer-to-Peer cluster + + + [uev]() + + - [uevent](tcllib/files/modules/uev/uevent.md) User events + + - [uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md) Request merging and deferal to idle time + + + [units]() + + - [units](tcllib/files/modules/units/units.md) unit conversion + + + [uri]() + + - [uri](tcllib/files/modules/uri/uri.md) URI utilities + + - [uri_urn](tcllib/files/modules/uri/urn-scheme.md) URI utilities, URN scheme + + + [uuid]() + + - [uuid](tcllib/files/modules/uuid/uuid.md) UUID generation and comparison + + + [valtype]() + + - [valtype::common](tcllib/files/modules/valtype/valtype_common.md) Validation, common code + + - [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) Validation for AMEX creditcard number + + - [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) Validation for Discover creditcard number + + - [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) Validation for Mastercard creditcard number + + - [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) Validation for VISA creditcard number + + - [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) Validation for EAN13 + + - [valtype::iban](tcllib/files/modules/valtype/iban.md) Validation for IBAN + + - [valtype::imei](tcllib/files/modules/valtype/imei.md) Validation for IMEI + + - [valtype::isbn](tcllib/files/modules/valtype/isbn.md) Validation for ISBN + + - [valtype::luhn](tcllib/files/modules/valtype/luhn.md) Validation for plain number with a LUHN checkdigit + + - [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) Validation for plain number with a LUHN5 checkdigit + + - [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) Validation for USNPI + + - [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md) Validation for plain number with a VERHOEFF checkdigit + + + [virtchannel_base]() + + - [tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) Concatenation channel + + - [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) Facade channel + + - [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) In-memory fifo channel + + - [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) In-memory interconnected fifo channels + + - [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) In-memory channel, half of a fifo2 + + - [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) In-memory channel + + - [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) Null channel + + - [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) Null/Zero channel combination + + - [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) Random channel + + - [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) Standard I/O, unification of stdin and stdout + + - [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) Read-only in-memory channel + + - [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) Textwindow channel + + - [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) In-memory channel using variable for storage + + - [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) Zero channel + + - [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) Utilities for random channels + + + [virtchannel_core]() + + - [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) Basic reflected/virtual channel support + + - [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) Event support for reflected/virtual channels + + - [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md) Basic reflected/virtual channel transform support + + + [virtchannel_transform]() + + - [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) Adler32 transformation + + - [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) Base64 encoding transformation + + - [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) Counter transformation + + - [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) Crc32 transformation + + - [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) Hexadecimal encoding transformation + + - [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) Identity transformation + + - [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) limiting input + + - [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) Observer transformation, stream copy + + - [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) Encryption via one-time pad + + - [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) rot-encryption + + - [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) Space insertation and removal + + - [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md) zlib (de)compression + + + [websocket]() + + - [websocket](tcllib/files/modules/websocket/websocket.md) Tcl implementation of the websocket protocol + + + [wip]() + + - [wip](tcllib/files/modules/wip/wip.md) Word Interpreter + + + [yaml]() + + - [huddle](tcllib/files/modules/yaml/huddle.md) Create and manipulate huddle object + + - [yaml](tcllib/files/modules/yaml/yaml.md) YAML Format Encoder/Decoder + + + [zip]() + + - [zipfile::decode](tcllib/files/modules/zip/decode.md) Access to zip archives + + - [zipfile::encode](tcllib/files/modules/zip/encode.md) Generation of zip archives + + - [zipfile::mkzip](tcllib/files/modules/zip/mkzip.md) Build a zip archive ADDED embedded/md/toc0.md Index: embedded/md/toc0.md ================================================================== --- /dev/null +++ embedded/md/toc0.md @@ -0,0 +1,920 @@ + +[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown') + +# Table Of Contents -- + + - [By Categories]() + + * [Argument entry form, mega widget]() + + + [tepam::argument_dialogbox](tcllib/files/modules/tepam/tepam_argument_dialogbox.md) TEPAM argument_dialogbox, reference manual + + * [Benchmark tools]() + + + [bench](tcllib/files/modules/bench/bench.md) bench - Processing benchmark suites + + + [bench::in](tcllib/files/modules/bench/bench_read.md) bench::in - Reading benchmark results + + + [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) bench::out::csv - Formatting benchmark results as CSV + + + [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) bench::out::text - Formatting benchmark results as human readable text + + + [bench_intro](tcllib/files/modules/bench/bench_intro.md) bench introduction + + + [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) bench language introduction + + + [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md) bench language specification + + * [CGI programming]() + + + [html](tcllib/files/modules/html/html.md) Procedures to generate HTML structures + + + [javascript](tcllib/files/modules/javascript/javascript.md) Procedures to generate HTML and Java Script structures. + + + [json](tcllib/files/modules/json/json.md) JSON parser + + + [json::write](tcllib/files/modules/json/json_write.md) JSON generation + + + [ncgi](tcllib/files/modules/ncgi/ncgi.md) Procedures to manipulate CGI values. + + * [Channels]() + + + [tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) Concatenation channel + + + [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) Basic reflected/virtual channel support + + + [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) Event support for reflected/virtual channels + + + [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) Facade channel + + + [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) In-memory fifo channel + + + [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) In-memory interconnected fifo channels + + + [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) In-memory channel, half of a fifo2 + + + [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) In-memory channel + + + [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) Null channel + + + [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) Null/Zero channel combination + + + [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) Random channel + + + [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) Standard I/O, unification of stdin and stdout + + + [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) Read-only in-memory channel + + + [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) Textwindow channel + + + [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) In-memory channel using variable for storage + + + [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) Zero channel + + + [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) Utilities for random channels + + + [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) Adler32 transformation + + + [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) Base64 encoding transformation + + + [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md) Basic reflected/virtual channel transform support + + + [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) Counter transformation + + + [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) Crc32 transformation + + + [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) Hexadecimal encoding transformation + + + [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) Identity transformation + + + [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) limiting input + + + [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) Observer transformation, stream copy + + + [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) Encryption via one-time pad + + + [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) rot-encryption + + + [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) Space insertation and removal + + + [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md) zlib (de)compression + + * [Coroutine]() + + + [coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) Coroutine based event and IO handling + + + [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) Automatic event and IO coroutine awareness + + * [Data structures]() + + + [counter](tcllib/files/modules/counter/counter.md) Procedures for counters and histograms + + + [report](tcllib/files/modules/report/report.md) Create and manipulate report objects + + + [struct::disjointset](tcllib/files/modules/struct/disjointset.md) Disjoint set data structure + + + [struct::graph](tcllib/files/modules/struct/graph.md) Create and manipulate directed graph objects + + + [struct::graph::op](tcllib/files/modules/struct/graphops.md) Operation for (un)directed graph objects + + + [struct::graph_v1](tcllib/files/modules/struct/graph1.md) Create and manipulate directed graph objects + + + [struct::list](tcllib/files/modules/struct/struct_list.md) Procedures for manipulating lists + + + [struct::matrix](tcllib/files/modules/struct/matrix.md) Create and manipulate matrix objects + + + [struct::matrix_v1](tcllib/files/modules/struct/matrix1.md) Create and manipulate matrix objects + + + [struct::pool](tcllib/files/modules/struct/pool.md) Create and manipulate pool objects (of discrete items) + + + [struct::prioqueue](tcllib/files/modules/struct/prioqueue.md) Create and manipulate prioqueue objects + + + [struct::queue](tcllib/files/modules/struct/queue.md) Create and manipulate queue objects + + + [struct::record](tcllib/files/modules/struct/record.md) Define and create records (similar to 'C' structures) + + + [struct::set](tcllib/files/modules/struct/struct_set.md) Procedures for manipulating sets + + + [struct::skiplist](tcllib/files/modules/struct/skiplist.md) Create and manipulate skiplists + + + [struct::stack](tcllib/files/modules/struct/stack.md) Create and manipulate stack objects + + + [struct::tree](tcllib/files/modules/struct/struct_tree.md) Create and manipulate tree objects + + + [struct::tree_v1](tcllib/files/modules/struct/struct_tree1.md) Create and manipulate tree objects + + + [treeql](tcllib/files/modules/treeql/treeql.md) Query tree objects + + * [debugging, tracing, and logging]() + + + [debug](tcllib/files/modules/debug/debug.md) debug narrative - core + + + [debug::caller](tcllib/files/modules/debug/debug_caller.md) debug narrative - caller + + + [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) debug narrative - heartbeat + + + [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md) debug narrative - timestamping + + * [Documentation tools]() + + + [docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) docidx introduction + + + [docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) docidx language command reference + + + [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) docidx language faq + + + [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) docidx language introduction + + + [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) docidx language syntax + + + [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) docidx plugin API reference + + + [docstrip](tcllib/files/modules/docstrip/docstrip.md) Docstrip style source code extraction + + + [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) Docstrip-related utilities + + + [doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) doctoc introduction + + + [doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) doctoc language command reference + + + [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) doctoc language faq + + + [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) doctoc language introduction + + + [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) doctoc language syntax + + + [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) doctoc plugin API reference + + + [doctools](tcllib/files/modules/doctools/doctools.md) doctools - Processing documents + + + [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) DocTools - Keyword indices + + + [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) DocTools - Tables of Contents + + + [doctools::changelog](tcllib/files/modules/doctools/changelog.md) Processing text in Emacs ChangeLog format + + + [doctools::cvs](tcllib/files/modules/doctools/cvs.md) Processing text in 'cvs log' format + + + [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) Default CSS style for HTML export plugins + + + [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) Holding keyword indices + + + [doctools::idx](tcllib/files/modules/doctools/docidx.md) docidx - Processing indices + + + [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) Exporting keyword indices + + + [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) Importing keyword indices + + + [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) Parsing text in docidx format + + + [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) Docidx serialization utilities + + + [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) Message catalog management for the various document parsers + + + [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) Message catalog for the docidx parser (C) + + + [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) Message catalog for the docidx parser (DE) + + + [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) Message catalog for the docidx parser (EN) + + + [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) Message catalog for the docidx parser (FR) + + + [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) Message catalog for the doctoc parser (C) + + + [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) Message catalog for the doctoc parser (DE) + + + [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) Message catalog for the doctoc parser (EN) + + + [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md) Message catalog for the doctoc parser (FR) + + + [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) Default CSS style for NROFF export plugins + + + [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) Processing text in 'subst -novariables' format + + + [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) Holding tables of contents + + + [doctools::toc](tcllib/files/modules/doctools/doctoc.md) doctoc - Processing tables of contents + + + [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) Exporting tables of contents + + + [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) Importing keyword indices + + + [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) Parsing text in doctoc format + + + [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) Doctoc serialization utilities + + + [doctools_intro](tcllib/files/modules/doctools/doctools_intro.md) doctools introduction + + + [doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) doctools language command reference + + + [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) doctools language faq + + + [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) doctools language introduction + + + [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md) doctools language syntax + + + [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md) doctools plugin API reference + + + [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) Lightweight DocTools Markup Processor + + + [dtplite](tcllib/files/apps/dtplite.md) Lightweight DocTools Markup Processor + + + [mpexpand](tcllib/files/modules/doctools/mpexpand.md) Markup processor + + + [tcldocstrip](tcllib/files/apps/tcldocstrip.md) Tcl-based Docstrip Processor + + + [tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md) TEPAM DOC Generation, reference manual + + + [textutil::expander](tcllib/files/modules/textutil/expander.md) Procedures to process templates and expand text. + + * [File]() + + + [zipfile::decode](tcllib/files/modules/zip/decode.md) Access to zip archives + + + [zipfile::encode](tcllib/files/modules/zip/encode.md) Generation of zip archives + + + [zipfile::mkzip](tcllib/files/modules/zip/mkzip.md) Build a zip archive + + * [File formats]() + + + [gpx](tcllib/files/modules/gpx/gpx.md) Extracts waypoints, tracks and routes from GPX files + + + [jpeg](tcllib/files/modules/jpeg/jpeg.md) JPEG querying and manipulation of meta data + + + [png](tcllib/files/modules/png/png.md) PNG querying and manipulation of meta data + + + [tar](tcllib/files/modules/tar/tar.md) Tar file creation, extraction & manipulation + + + [tiff](tcllib/files/modules/tiff/tiff.md) TIFF reading, writing, and querying and manipulation of meta data + + * [Grammars and finite automata]() + + + [grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) Aycock-Horspool-Earley parser generator for Tcl + + + [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) Create and manipulate finite automatons + + + [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) Create and use deterministic acceptors + + + [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) Execute deterministic finite automatons + + + [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) Operations on finite automatons + + + [grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) Virtual machine implementation II for parsing token streams + + + [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) ME virtual machine state manipulation + + + [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) ME assembler + + + [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) Virtual machine implementation I for parsing token streams + + + [grammar::me::util](tcllib/files/modules/grammar_me/me_util.md) AST utilities + + + [grammar::me_ast](tcllib/files/modules/grammar_me/me_ast.md) Various representations of ASTs + + + [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) Introduction to virtual machines for parsing token streams + + + [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) Virtual machine for parsing token streams + + + [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) Create and manipulate parsing expression grammars + + + [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) Interpreter for parsing expression grammars + + * [Hashes, checksums, and encryption]() + + + [aes](tcllib/files/modules/aes/aes.md) Implementation of the AES block cipher + + + [blowfish](tcllib/files/modules/blowfish/blowfish.md) Implementation of the Blowfish block cipher + + + [cksum](tcllib/files/modules/crc/cksum.md) Calculate a cksum(1) compatible checksum + + + [crc16](tcllib/files/modules/crc/crc16.md) Perform a 16bit Cyclic Redundancy Check + + + [crc32](tcllib/files/modules/crc/crc32.md) Perform a 32bit Cyclic Redundancy Check + + + [des](tcllib/files/modules/des/des.md) Implementation of the DES and triple-DES ciphers + + + [md4](tcllib/files/modules/md4/md4.md) MD4 Message-Digest Algorithm + + + [md5](tcllib/files/modules/md5/md5.md) MD5 Message-Digest Algorithm + + + [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) MD5-based password encryption + + + [otp](tcllib/files/modules/otp/otp.md) One-Time Passwords + + + [pki](tcllib/files/modules/pki/pki.md) Implementation of the public key cipher + + + [rc4](tcllib/files/modules/rc4/rc4.md) Implementation of the RC4 stream cipher + + + [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) RIPEMD-128 Message-Digest Algorithm + + + [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) RIPEMD-160 Message-Digest Algorithm + + + [sha1](tcllib/files/modules/sha1/sha1.md) SHA1 Message-Digest Algorithm + + + [sha256](tcllib/files/modules/sha1/sha256.md) SHA256 Message-Digest Algorithm + + + [soundex](tcllib/files/modules/soundex/soundex.md) Soundex + + + [sum](tcllib/files/modules/crc/sum.md) Calculate a sum(1) compatible checksum + + + [tclDES](tcllib/files/modules/des/tcldes.md) Implementation of the DES and triple-DES ciphers + + + [tclDESjr](tcllib/files/modules/des/tcldesjr.md) Implementation of the DES and triple-DES ciphers + + + [uuid](tcllib/files/modules/uuid/uuid.md) UUID generation and comparison + + * [Mathematics]() + + + [math](tcllib/files/modules/math/math.md) Tcl Math Library + + + [math::bigfloat](tcllib/files/modules/math/bigfloat.md) Arbitrary precision floating-point numbers + + + [math::bignum](tcllib/files/modules/math/bignum.md) Arbitrary precision integer numbers + + + [math::calculus](tcllib/files/modules/math/calculus.md) Integration and ordinary differential equations + + + [math::calculus::romberg](tcllib/files/modules/math/romberg.md) Romberg integration + + + [math::combinatorics](tcllib/files/modules/math/combinatorics.md) Combinatorial functions in the Tcl Math Library + + + [math::complexnumbers](tcllib/files/modules/math/qcomplex.md) Straightforward complex number package + + + [math::constants](tcllib/files/modules/math/constants.md) Mathematical and numerical constants + + + [math::decimal](tcllib/files/modules/math/decimal.md) General decimal arithmetic + + + [math::exact](tcllib/files/modules/math/exact.md) Exact Real Arithmetic + + + [math::fourier](tcllib/files/modules/math/fourier.md) Discrete and fast fourier transforms + + + [math::fuzzy](tcllib/files/modules/math/fuzzy.md) Fuzzy comparison of floating-point numbers + + + [math::geometry](tcllib/files/modules/math/math_geometry.md) Geometrical computations + + + [math::interpolate](tcllib/files/modules/math/interpolate.md) Interpolation routines + + + [math::linearalgebra](tcllib/files/modules/math/linalg.md) Linear Algebra + + + [math::numtheory](tcllib/files/modules/math/numtheory.md) Number Theory + + + [math::optimize](tcllib/files/modules/math/optimize.md) Optimisation routines + + + [math::PCA](tcllib/files/modules/math/pca.md) Package for Principal Component Analysis + + + [math::polynomials](tcllib/files/modules/math/polynomials.md) Polynomial functions + + + [math::rationalfunctions](tcllib/files/modules/math/rational_funcs.md) Polynomial functions + + + [math::roman](tcllib/files/modules/math/roman.md) Tools for creating and manipulating roman numerals + + + [math::special](tcllib/files/modules/math/special.md) Special mathematical functions + + + [math::statistics](tcllib/files/modules/math/statistics.md) Basic statistical functions and procedures + + + [math::trig](tcllib/files/modules/math/trig.md) Trigonometric anf hyperbolic functions + + + [simulation::annealing](tcllib/files/modules/simulation/annealing.md) Simulated annealing + + + [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md) Monte Carlo simulations + + + [simulation::random](tcllib/files/modules/simulation/simulation_random.md) Pseudo-random number generators + + * [Networking]() + + + [asn](tcllib/files/modules/asn/asn.md) ASN.1 BER encoder/decoder + + + [autoproxy](tcllib/files/modules/http/autoproxy.md) Automatic HTTP proxy usage and authentication + + + [bee](tcllib/files/modules/bee/bee.md) BitTorrent Serialization Format Encoder/Decoder + + + [dns](tcllib/files/modules/dns/tcllib_dns.md) Tcl Domain Name Service Client + + + [ftp](tcllib/files/modules/ftp/ftp.md) Client-side tcl implementation of the ftp protocol + + + [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) Uri handler for ftp urls + + + [ftpd](tcllib/files/modules/ftpd/ftpd.md) Tcl FTP server implementation + + + [ident](tcllib/files/modules/ident/ident.md) Ident protocol client + + + [irc](tcllib/files/modules/irc/irc.md) Create IRC connection and interface. + + + [ldap](tcllib/files/modules/ldap/ldap.md) LDAP client + + + [ldapx](tcllib/files/modules/ldap/ldapx.md) LDAP extended object interface + + + [nameserv](tcllib/files/modules/nns/nns_client.md) Name service facility, Client + + + [nameserv::auto](tcllib/files/modules/nns/nns_auto.md) Name service facility, Client Extension + + + [nameserv::common](tcllib/files/modules/nns/nns_common.md) Name service facility, shared definitions + + + [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md) Name service facility, client/server protocol + + + [nameserv::server](tcllib/files/modules/nns/nns_server.md) Name service facility, Server + + + [nmea](tcllib/files/modules/nmea/nmea.md) Process NMEA data + + + [nns](tcllib/files/apps/nns.md) Name service facility, Commandline Client Application + + + [nns_intro](tcllib/files/modules/nns/nns_intro.md) Name service facility, introduction + + + [nnsd](tcllib/files/apps/nnsd.md) Name service facility, Commandline Server Application + + + [nnslog](tcllib/files/apps/nnslog.md) Name service facility, Commandline Logging Client Application + + + [nntp](tcllib/files/modules/nntp/nntp.md) Tcl client for the NNTP protocol + + + [ntp_time](tcllib/files/modules/ntp/ntp_time.md) Tcl Time Service Client + + + [oauth](tcllib/files/modules/oauth/oauth.md) oauth API base signature + + + [picoirc](tcllib/files/modules/irc/picoirc.md) Small and simple embeddable IRC client. + + + [pop3](tcllib/files/modules/pop3/pop3.md) Tcl client for POP3 email protocol + + + [pop3d](tcllib/files/modules/pop3d/pop3d.md) Tcl POP3 server implementation + + + [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) Simple mailbox database for pop3d + + + [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md) Simple user database for pop3d + + + [S3](tcllib/files/modules/amazon-s3/S3.md) Amazon S3 Web Service Interface + + + [SASL](tcllib/files/modules/sasl/sasl.md) Implementation of SASL mechanisms for Tcl + + + [SASL::NTLM](tcllib/files/modules/sasl/ntlm.md) Implementation of SASL NTLM mechanism for Tcl + + + [SASL::SCRAM](tcllib/files/modules/sasl/scram.md) Implementation of SASL SCRAM mechanism for Tcl + + + [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md) Implementation of SASL NTLM mechanism for Tcl + + + [smtp](tcllib/files/modules/mime/smtp.md) Client-side tcl implementation of the smtp protocol + + + [smtpd](tcllib/files/modules/smtpd/smtpd.md) Tcl SMTP server implementation + + + [tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md) IPv4 and IPv6 address manipulation + + + [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 + + + [websocket](tcllib/files/modules/websocket/websocket.md) Tcl implementation of the websocket protocol + + * [Page Parser Generator]() + + + [page](tcllib/files/apps/page.md) Parser Generator + + + [page_intro](tcllib/files/modules/page/page_intro.md) page introduction + + + [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) page plugin manager + + + [page_util_flow](tcllib/files/modules/page/page_util_flow.md) page dataflow/treewalker utility + + + [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) page AST normalization, LEMON + + + [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) page AST normalization, PEG + + + [page_util_peg](tcllib/files/modules/page/page_util_peg.md) page PEG transformation utilities + + + [page_util_quote](tcllib/files/modules/page/page_util_quote.md) page character quoting utilities + + * [Parsing and Grammars]() + + + [pt](tcllib/files/apps/pt.md) Parser Tools Application + + + [pt::ast](tcllib/files/modules/pt/pt_astree.md) Abstract Syntax Tree Serialization + + + [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) C/PARAM, Canned configuration, Critcl + + + [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) C/PARAM, Canned configuration, TEA + + + [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) The JSON Grammar Exchange Format + + + [pt::param](tcllib/files/modules/pt/pt_param.md) PackRat Machine Specification + + + [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) Parsing Expression Serialization + + + [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) Parsing Expression Utilities + + + [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) Parsing Expression Grammar Serialization + + + [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) PEG Storage + + + [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) PEG Storage. Canned PEG grammar specification + + + [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) PEG Export + + + [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) PEG Export Plugin. Write CONTAINER format + + + [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) PEG Export Plugin. Write JSON format + + + [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) PEG Export Plugin. Write PEG format + + + [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) PEG Conversion. From CONTAINER format + + + [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) PEG Conversion. Read JSON format + + + [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) PEG Conversion. Read PEG format + + + [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) PEG Import + + + [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) PEG Import Plugin. From CONTAINER format + + + [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) PEG Import Plugin. Read JSON format + + + [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) PEG Import Plugin. Read PEG format + + + [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) Interpreter for parsing expression grammars + + + [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) PEG Conversion. Write CONTAINER format + + + [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) PEG Conversion. Write CPARAM format + + + [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) PEG Conversion. Write JSON format + + + [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) PEG Conversion. Write PARAM format + + + [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) PEG Conversion. Write PEG format + + + [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) PEG Conversion. Write TCLPARAM format + + + [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) PEG Language Tutorial + + + [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) Introduction to Parsing Expression Grammars + + + [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) Parser Generator + + + [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) Parsing Runtime Support, PARAM based + + + [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) Tcl/PARAM, Canned configuration, NX + + + [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) Tcl/PARAM, Canned configuration, Snit + + + [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) Tcl/PARAM, Canned configuration, Tcloo + + + [pt::util](tcllib/files/modules/pt/pt_util.md) General utilities + + + [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) Parser Tools Export API + + + [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) Parser Tools Import API + + + [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) Introduction to Parser Tools + + + [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) Parser Tools PEG Parser + + + [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) Parser API + + + [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md) Parser Tools PE Grammar Utility Operations + + * [Procedures, arguments, parameters, options]() + + + [tepam](tcllib/files/modules/tepam/tepam_introduction.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager + + + [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md) TEPAM procedure, reference manual + + * [Programming tools]() + + + [cmdline](tcllib/files/modules/cmdline/cmdline.md) Procedures to process command lines and options. + + + [comm](tcllib/files/modules/comm/comm.md) A remote communication facility for Tcl (8.3 and later) + + + [comm_wire](tcllib/files/modules/comm/comm_wire.md) The comm wire protocol + + + [control](tcllib/files/modules/control/control.md) Procedures for control flow structures. + + + [deleg_method](tcllib/files/modules/interp/deleg_method.md) Creation of comm delegates (snit methods) + + + [deleg_proc](tcllib/files/modules/interp/deleg_proc.md) Creation of comm delegates (procedures) + + + [fileutil](tcllib/files/modules/fileutil/fileutil.md) Procedures implementing some file utilities + + + [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) Generator core for compiler of magic(5) files + + + [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) Generator core for compiler of magic(5) files + + + [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) Procedures implementing file-type recognition + + + [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) Runtime core for file type recognition engines written in pure Tcl + + + [fileutil::multi](tcllib/files/modules/fileutil/multi.md) Multi-file operation, scatter/gather, standard object + + + [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md) Multi-file operation, scatter/gather + + + [fileutil_traverse](tcllib/files/modules/fileutil/traverse.md) Iterative directory traversal + + + [hook](tcllib/files/modules/hook/hook.md) Hooks + + + [interp](tcllib/files/modules/interp/tcllib_interp.md) Interp creation and aliasing + + + [log](tcllib/files/modules/log/log.md) Procedures to log messages of libraries and applications. + + + [logger](tcllib/files/modules/log/logger.md) System to control logging of events. + + + [logger::appender](tcllib/files/modules/log/loggerAppender.md) Collection of predefined appenders for logger + + + [logger::utils](tcllib/files/modules/log/loggerUtils.md) Utilities for logger + + + [multiplexer](tcllib/files/modules/multiplexer/multiplexer.md) One-to-many communication with sockets. + + + [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr.md) Manage a plugin + + + [profiler](tcllib/files/modules/profiler/profiler.md) Tcl source code profiler + + + [snit](tcllib/files/modules/snit/snit.md) Snit's Not Incr Tcl + + + [snitfaq](tcllib/files/modules/snit/snitfaq.md) Snit Frequently Asked Questions + + + [stooop](tcllib/files/modules/stooop/stooop.md) Object oriented extension. + + + [switched](tcllib/files/modules/stooop/switched.md) switch/option management. + + + [tie](tcllib/files/modules/tie/tie.md) Array persistence + + + [tie](tcllib/files/modules/tie/tie_std.md) Array persistence, standard data sources + + + [uevent](tcllib/files/modules/uev/uevent.md) User events + + + [wip](tcllib/files/modules/wip/wip.md) Word Interpreter + + * [System]() + + + [cron](tcllib/files/modules/cron/cron.md) Tool for automating the period callback of commands + + + [nettool](tcllib/files/modules/nettool/nettool.md) Tools for networked applications + + + [processman](tcllib/files/modules/processman/processman.md) Tool for automating the period callback of commands + + * [TclOO]() + + + [oometa](tcllib/files/modules/oometa/oometa.md) oo::meta A data registry for classess + + + [practcl](tcllib/files/modules/practcl/practcl.md) The Practcl Module + + + [tool](tcllib/files/modules/tool/tool.md) TclOO Library (TOOL) Framework + + * [Terminal control]() + + + [term](tcllib/files/modules/term/term.md) General terminal control + + + [term::ansi::code](tcllib/files/modules/term/ansi_code.md) Helper for control sequences + + + [term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) ANSI attribute sequences + + + [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) ANSI control sequences + + + [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) Macro sequences + + + [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md) Control operations and queries + + + [term::ansi::send](tcllib/files/modules/term/ansi_send.md) Output of ANSI control sequences to terminals + + + [term::interact::menu](tcllib/files/modules/term/imenu.md) Terminal widget, menu + + + [term::interact::pager](tcllib/files/modules/term/ipager.md) Terminal widget, paging + + + [term::receive](tcllib/files/modules/term/receive.md) General input from terminals + + + [term::receive::bind](tcllib/files/modules/term/term_bind.md) Keyboard dispatch from terminals + + + [term::send](tcllib/files/modules/term/term_send.md) General output to terminals + + * [Text formatter plugin]() + + + [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) docidx export plugin + + + [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) HTML export plugin + + + [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) JSON export plugin + + + [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) nroff export plugin + + + [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) plain text export plugin + + + [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) wiki export plugin + + + [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) docidx import plugin + + + [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) JSON import plugin + + + [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) doctoc export plugin + + + [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) HTML export plugin + + + [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) JSON export plugin + + + [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) nroff export plugin + + + [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) plain text export plugin + + + [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) wiki export plugin + + + [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) doctoc import plugin + + + [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) JSON import plugin + + * [Text processing]() + + + [ascii85](tcllib/files/modules/base64/ascii85.md) ascii85-encode/decode binary data + + + [base32](tcllib/files/modules/base32/base32.md) base32 standard encoding + + + [base32::core](tcllib/files/modules/base32/base32core.md) Expanding basic base32 maps + + + [base32::hex](tcllib/files/modules/base32/base32hex.md) base32 extended hex encoding + + + [base64](tcllib/files/modules/base64/base64.md) base64-encode/decode binary data + + + [bibtex](tcllib/files/modules/bibtex/bibtex.md) Parse bibtex files + + + [clock_iso8601](tcllib/files/modules/clock/iso8601.md) Parsing ISO 8601 dates/times + + + [clock_rfc2822](tcllib/files/modules/clock/rfc2822.md) Parsing ISO 8601 dates/times + + + [csv](tcllib/files/modules/csv/csv.md) Procedures to handle CSV data. + + + [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) Procedures to parse HTML strings + + + [inifile](tcllib/files/modules/inifile/ini.md) Parsing of Windows INI files + + + [markdown](tcllib/files/modules/markdown/markdown.md) Converts Markdown text to HTML + + + [mime](tcllib/files/modules/mime/mime.md) Manipulation of MIME body parts + + + [rcs](tcllib/files/modules/rcs/rcs.md) RCS low level utilities + + + [string::token](tcllib/files/modules/string/token.md) Regex based iterative lexing + + + [string::token::shell](tcllib/files/modules/string/token_shell.md) Parsing of shell command line + + + [textutil](tcllib/files/modules/textutil/textutil.md) Procedures to manipulate texts and strings. + + + [textutil::adjust](tcllib/files/modules/textutil/adjust.md) Procedures to adjust, indent, and undent paragraphs + + + [textutil::repeat](tcllib/files/modules/textutil/repeat.md) Procedures to repeat strings. + + + [textutil::split](tcllib/files/modules/textutil/textutil_split.md) Procedures to split texts + + + [textutil::string](tcllib/files/modules/textutil/textutil_string.md) Procedures to manipulate texts and strings. + + + [textutil::tabify](tcllib/files/modules/textutil/tabify.md) Procedures to (un)tabify strings + + + [textutil::trim](tcllib/files/modules/textutil/trim.md) Procedures to trim strings + + + [uuencode](tcllib/files/modules/base64/uuencode.md) UU-encode/decode binary data + + + [xsxp](tcllib/files/modules/amazon-s3/xsxp.md) eXtremely Simple Xml Parser + + + [yencode](tcllib/files/modules/base64/yencode.md) Y-encode/decode binary data + + * [Transfer module]() + + + [transfer::connect](tcllib/files/modules/transfer/connect.md) Connection setup + + + [transfer::copy](tcllib/files/modules/transfer/copyops.md) Data transfer foundation + + + [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) Queued transfers + + + [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) Data destination + + + [transfer::data::source](tcllib/files/modules/transfer/dsource.md) Data source + + + [transfer::receiver](tcllib/files/modules/transfer/receiver.md) Data source + + + [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md) Data source + + * [Unfiled]() + + + [cache::async](tcllib/files/modules/cache/async.md) Asynchronous in-memory cache + + + [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 + + + [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) Accessing a server providing tiles for slippy-based maps + + + [mapproj](tcllib/files/modules/mapproj/mapproj.md) Map projection routines + + + [math::calculus::symdiff](tcllib/files/modules/math/symdiff.md) Symbolic differentiation for Tcl + + + [namespacex](tcllib/files/modules/namespacex/namespacex.md) Namespace utility commands + + + [rest](tcllib/files/modules/rest/rest.md) define REST web APIs and call them inline or asychronously + + + [stringprep](tcllib/files/modules/stringprep/stringprep.md) Implementation of stringprep + + + [stringprep::data](tcllib/files/modules/stringprep/stringprep_data.md) stringprep data tables, generated, internal + + + [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 + + + [unicode](tcllib/files/modules/stringprep/unicode.md) Implementation of Unicode normalization + + + [unicode::data](tcllib/files/modules/stringprep/unicode_data.md) unicode data tables, generated, internal + + + [units](tcllib/files/modules/units/units.md) unit conversion + + + [yaml](tcllib/files/modules/yaml/yaml.md) YAML Format Encoder/Decoder + + * [Utilities]() + + + [dicttool](tcllib/files/modules/dicttool/dicttool.md) Dictionary Tools + + * [Utility]() + + + [defer](tcllib/files/modules/defer/defer.md) Defered execution + + + [lambda](tcllib/files/modules/lambda/lambda.md) Utility commands for anonymous procedures + + + [lazyset](tcllib/files/modules/lazyset/lazyset.md) Lazy evaluation + + + [oo::util](tcllib/files/modules/ooutil/ooutil.md) Utility commands for TclOO + + + [oo::util](tcllib/files/modules/tool/meta.md) Utility commands for TclOO + + + [throw](tcllib/files/modules/try/tcllib_throw.md) throw - Throw an error exception with a message + + + [tool::dict_ensemble](tcllib/files/modules/tool/tool_dict_ensemble.md) Dictionary Tools + + + [try](tcllib/files/modules/try/tcllib_try.md) try - Trap and process errors and exceptions + + * [Validation, Type checking]() + + + [valtype::common](tcllib/files/modules/valtype/valtype_common.md) Validation, common code + + + [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) Validation for AMEX creditcard number + + + [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) Validation for Discover creditcard number + + + [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) Validation for Mastercard creditcard number + + + [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) Validation for VISA creditcard number + + + [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) Validation for EAN13 + + + [valtype::iban](tcllib/files/modules/valtype/iban.md) Validation for IBAN + + + [valtype::imei](tcllib/files/modules/valtype/imei.md) Validation for IMEI + + + [valtype::isbn](tcllib/files/modules/valtype/isbn.md) Validation for ISBN + + + [valtype::luhn](tcllib/files/modules/valtype/luhn.md) Validation for plain number with a LUHN checkdigit + + + [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) Validation for plain number with a LUHN5 checkdigit + + + [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) Validation for USNPI + + + [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md) Validation for plain number with a VERHOEFF checkdigit ADDED embedded/md/toc1.md Index: embedded/md/toc1.md ================================================================== --- /dev/null +++ embedded/md/toc1.md @@ -0,0 +1,1100 @@ + +[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown') + +# Table Of Contents -- + + - [Modules]() + + * [aes]() + + + [aes](tcllib/files/modules/aes/aes.md) Implementation of the AES block cipher + + * [amazon-s3]() + + + [S3](tcllib/files/modules/amazon-s3/S3.md) Amazon S3 Web Service Interface + + + [xsxp](tcllib/files/modules/amazon-s3/xsxp.md) eXtremely Simple Xml Parser + + * [asn]() + + + [asn](tcllib/files/modules/asn/asn.md) ASN.1 BER encoder/decoder + + * [base32]() + + + [base32](tcllib/files/modules/base32/base32.md) base32 standard encoding + + + [base32::core](tcllib/files/modules/base32/base32core.md) Expanding basic base32 maps + + + [base32::hex](tcllib/files/modules/base32/base32hex.md) base32 extended hex encoding + + * [base64]() + + + [ascii85](tcllib/files/modules/base64/ascii85.md) ascii85-encode/decode binary data + + + [base64](tcllib/files/modules/base64/base64.md) base64-encode/decode binary data + + + [uuencode](tcllib/files/modules/base64/uuencode.md) UU-encode/decode binary data + + + [yencode](tcllib/files/modules/base64/yencode.md) Y-encode/decode binary data + + * [bee]() + + + [bee](tcllib/files/modules/bee/bee.md) BitTorrent Serialization Format Encoder/Decoder + + * [bench]() + + + [bench](tcllib/files/modules/bench/bench.md) bench - Processing benchmark suites + + + [bench::in](tcllib/files/modules/bench/bench_read.md) bench::in - Reading benchmark results + + + [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) bench::out::csv - Formatting benchmark results as CSV + + + [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) bench::out::text - Formatting benchmark results as human readable text + + + [bench_intro](tcllib/files/modules/bench/bench_intro.md) bench introduction + + + [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) bench language introduction + + + [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md) bench language specification + + * [bibtex]() + + + [bibtex](tcllib/files/modules/bibtex/bibtex.md) Parse bibtex files + + * [blowfish]() + + + [blowfish](tcllib/files/modules/blowfish/blowfish.md) Implementation of the Blowfish block cipher + + * [cache]() + + + [cache::async](tcllib/files/modules/cache/async.md) Asynchronous in-memory cache + + * [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 + + * [cmdline]() + + + [cmdline](tcllib/files/modules/cmdline/cmdline.md) Procedures to process command lines and options. + + * [comm]() + + + [comm](tcllib/files/modules/comm/comm.md) A remote communication facility for Tcl (8.3 and later) + + + [comm_wire](tcllib/files/modules/comm/comm_wire.md) The comm wire protocol + + * [control]() + + + [control](tcllib/files/modules/control/control.md) Procedures for control flow structures. + + * [coroutine]() + + + [coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) Coroutine based event and IO handling + + + [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) Automatic event and IO coroutine awareness + + * [counter]() + + + [counter](tcllib/files/modules/counter/counter.md) Procedures for counters and histograms + + * [crc]() + + + [cksum](tcllib/files/modules/crc/cksum.md) Calculate a cksum(1) compatible checksum + + + [crc16](tcllib/files/modules/crc/crc16.md) Perform a 16bit Cyclic Redundancy Check + + + [crc32](tcllib/files/modules/crc/crc32.md) Perform a 32bit Cyclic Redundancy Check + + + [sum](tcllib/files/modules/crc/sum.md) Calculate a sum(1) compatible checksum + + * [cron]() + + + [cron](tcllib/files/modules/cron/cron.md) Tool for automating the period callback of commands + + * [csv]() + + + [csv](tcllib/files/modules/csv/csv.md) Procedures to handle CSV data. + + * [debug]() + + + [debug](tcllib/files/modules/debug/debug.md) debug narrative - core + + + [debug::caller](tcllib/files/modules/debug/debug_caller.md) debug narrative - caller + + + [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) debug narrative - heartbeat + + + [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md) debug narrative - timestamping + + * [defer]() + + + [defer](tcllib/files/modules/defer/defer.md) Defered execution + + * [des]() + + + [des](tcllib/files/modules/des/des.md) Implementation of the DES and triple-DES ciphers + + + [tclDES](tcllib/files/modules/des/tcldes.md) Implementation of the DES and triple-DES ciphers + + + [tclDESjr](tcllib/files/modules/des/tcldesjr.md) Implementation of the DES and triple-DES ciphers + + * [dicttool]() + + + [dicttool](tcllib/files/modules/dicttool/dicttool.md) Dictionary Tools + + * [dns]() + + + [dns](tcllib/files/modules/dns/tcllib_dns.md) Tcl Domain Name Service Client + + + [tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md) IPv4 and IPv6 address manipulation + + * [docstrip]() + + + [docstrip](tcllib/files/modules/docstrip/docstrip.md) Docstrip style source code extraction + + + [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) Docstrip-related utilities + + * [doctools]() + + + [docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) docidx introduction + + + [docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) docidx language command reference + + + [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) docidx language faq + + + [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) docidx language introduction + + + [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) docidx language syntax + + + [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) docidx plugin API reference + + + [doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) doctoc introduction + + + [doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) doctoc language command reference + + + [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) doctoc language faq + + + [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) doctoc language introduction + + + [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) doctoc language syntax + + + [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) doctoc plugin API reference + + + [doctools](tcllib/files/modules/doctools/doctools.md) doctools - Processing documents + + + [doctools::changelog](tcllib/files/modules/doctools/changelog.md) Processing text in Emacs ChangeLog format + + + [doctools::cvs](tcllib/files/modules/doctools/cvs.md) Processing text in 'cvs log' format + + + [doctools::idx](tcllib/files/modules/doctools/docidx.md) docidx - Processing indices + + + [doctools::toc](tcllib/files/modules/doctools/doctoc.md) doctoc - Processing tables of contents + + + [doctools_intro](tcllib/files/modules/doctools/doctools_intro.md) doctools introduction + + + [doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) doctools language command reference + + + [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) doctools language faq + + + [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) doctools language introduction + + + [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md) doctools language syntax + + + [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md) doctools plugin API reference + + + [mpexpand](tcllib/files/modules/doctools/mpexpand.md) Markup processor + + * [doctools2base]() + + + [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) Default CSS style for HTML export plugins + + + [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) Message catalog management for the various document parsers + + + [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) Default CSS style for NROFF export plugins + + + [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) Processing text in 'subst -novariables' format + + * [doctools2idx]() + + + [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) DocTools - Keyword indices + + + [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) Holding keyword indices + + + [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) Exporting keyword indices + + + [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) docidx export plugin + + + [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) HTML export plugin + + + [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) JSON export plugin + + + [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) nroff export plugin + + + [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) plain text export plugin + + + [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) wiki export plugin + + + [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) Importing keyword indices + + + [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) docidx import plugin + + + [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) JSON import plugin + + + [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) Parsing text in docidx format + + + [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) Docidx serialization utilities + + + [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) Message catalog for the docidx parser (C) + + + [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) Message catalog for the docidx parser (DE) + + + [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) Message catalog for the docidx parser (EN) + + + [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) Message catalog for the docidx parser (FR) + + * [doctools2toc]() + + + [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) DocTools - Tables of Contents + + + [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) Message catalog for the doctoc parser (C) + + + [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) Message catalog for the doctoc parser (DE) + + + [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) Message catalog for the doctoc parser (EN) + + + [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md) Message catalog for the doctoc parser (FR) + + + [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) Holding tables of contents + + + [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) Exporting tables of contents + + + [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) doctoc export plugin + + + [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) HTML export plugin + + + [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) JSON export plugin + + + [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) nroff export plugin + + + [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) plain text export plugin + + + [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) wiki export plugin + + + [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) Importing keyword indices + + + [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) doctoc import plugin + + + [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) JSON import plugin + + + [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) Parsing text in doctoc format + + + [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) Doctoc serialization utilities + + * [dtplite]() + + + [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) Lightweight DocTools Markup Processor + + * [fileutil]() + + + [fileutil](tcllib/files/modules/fileutil/fileutil.md) Procedures implementing some file utilities + + + [fileutil::multi](tcllib/files/modules/fileutil/multi.md) Multi-file operation, scatter/gather, standard object + + + [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md) Multi-file operation, scatter/gather + + + [fileutil_traverse](tcllib/files/modules/fileutil/traverse.md) Iterative directory traversal + + * [ftp]() + + + [ftp](tcllib/files/modules/ftp/ftp.md) Client-side tcl implementation of the ftp protocol + + + [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) Uri handler for ftp urls + + * [ftpd]() + + + [ftpd](tcllib/files/modules/ftpd/ftpd.md) Tcl FTP server implementation + + * [fumagic]() + + + [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) Generator core for compiler of magic(5) files + + + [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) Generator core for compiler of magic(5) files + + + [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) Procedures implementing file-type recognition + + + [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) Runtime core for file type recognition engines written in pure Tcl + + * [generator]() + + + [generator](tcllib/files/modules/generator/generator.md) Procedures for creating and using generators. + + * [gpx]() + + + [gpx](tcllib/files/modules/gpx/gpx.md) Extracts waypoints, tracks and routes from GPX files + + * [grammar_aycock]() + + + [grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) Aycock-Horspool-Earley parser generator for Tcl + + * [grammar_fa]() + + + [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) Create and manipulate finite automatons + + + [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) Create and use deterministic acceptors + + + [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) Execute deterministic finite automatons + + + [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) Operations on finite automatons + + * [grammar_me]() + + + [grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) Virtual machine implementation II for parsing token streams + + + [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) ME virtual machine state manipulation + + + [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) ME assembler + + + [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) Virtual machine implementation I for parsing token streams + + + [grammar::me::util](tcllib/files/modules/grammar_me/me_util.md) AST utilities + + + [grammar::me_ast](tcllib/files/modules/grammar_me/me_ast.md) Various representations of ASTs + + + [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) Introduction to virtual machines for parsing token streams + + + [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) Virtual machine for parsing token streams + + * [grammar_peg]() + + + [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) Create and manipulate parsing expression grammars + + + [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) Interpreter for parsing expression grammars + + * [hook]() + + + [hook](tcllib/files/modules/hook/hook.md) Hooks + + * [html]() + + + [html](tcllib/files/modules/html/html.md) Procedures to generate HTML structures + + * [htmlparse]() + + + [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) Procedures to parse HTML strings + + * [http]() + + + [autoproxy](tcllib/files/modules/http/autoproxy.md) Automatic HTTP proxy usage and authentication + + * [httpd]() + + + [tool](tcllib/files/modules/httpd/httpd.md) A TclOO and coroutine based web server + + * [ident]() + + + [ident](tcllib/files/modules/ident/ident.md) Ident protocol client + + * [imap4]() + + + [imap4](tcllib/files/modules/imap4/imap4.md) imap client-side tcl implementation of imap protocol + + * [inifile]() + + + [inifile](tcllib/files/modules/inifile/ini.md) Parsing of Windows INI files + + * [interp]() + + + [deleg_method](tcllib/files/modules/interp/deleg_method.md) Creation of comm delegates (snit methods) + + + [deleg_proc](tcllib/files/modules/interp/deleg_proc.md) Creation of comm delegates (procedures) + + + [interp](tcllib/files/modules/interp/tcllib_interp.md) Interp creation and aliasing + + * [irc]() + + + [irc](tcllib/files/modules/irc/irc.md) Create IRC connection and interface. + + + [picoirc](tcllib/files/modules/irc/picoirc.md) Small and simple embeddable IRC client. + + * [javascript]() + + + [javascript](tcllib/files/modules/javascript/javascript.md) Procedures to generate HTML and Java Script structures. + + * [jpeg]() + + + [jpeg](tcllib/files/modules/jpeg/jpeg.md) JPEG querying and manipulation of meta data + + * [json]() + + + [json](tcllib/files/modules/json/json.md) JSON parser + + + [json::write](tcllib/files/modules/json/json_write.md) JSON generation + + * [lambda]() + + + [lambda](tcllib/files/modules/lambda/lambda.md) Utility commands for anonymous procedures + + * [lazyset]() + + + [lazyset](tcllib/files/modules/lazyset/lazyset.md) Lazy evaluation + + * [ldap]() + + + [ldap](tcllib/files/modules/ldap/ldap.md) LDAP client + + + [ldapx](tcllib/files/modules/ldap/ldapx.md) LDAP extended object interface + + * [log]() + + + [log](tcllib/files/modules/log/log.md) Procedures to log messages of libraries and applications. + + + [logger](tcllib/files/modules/log/logger.md) System to control logging of events. + + + [logger::appender](tcllib/files/modules/log/loggerAppender.md) Collection of predefined appenders for logger + + + [logger::utils](tcllib/files/modules/log/loggerUtils.md) Utilities for logger + + * [map]() + + + [map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) Resolving geographical names with a Nominatim service + + + [map::slippy](tcllib/files/modules/map/map_slippy.md) Common code for slippy based map packages + + + [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) Management of a tile cache in the local filesystem + + + [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) Accessing a server providing tiles for slippy-based maps + + * [mapproj]() + + + [mapproj](tcllib/files/modules/mapproj/mapproj.md) Map projection routines + + * [markdown]() + + + [markdown](tcllib/files/modules/markdown/markdown.md) Converts Markdown text to HTML + + * [math]() + + + [math](tcllib/files/modules/math/math.md) Tcl Math Library + + + [math::bigfloat](tcllib/files/modules/math/bigfloat.md) Arbitrary precision floating-point numbers + + + [math::bignum](tcllib/files/modules/math/bignum.md) Arbitrary precision integer numbers + + + [math::calculus](tcllib/files/modules/math/calculus.md) Integration and ordinary differential equations + + + [math::calculus::romberg](tcllib/files/modules/math/romberg.md) Romberg integration + + + [math::calculus::symdiff](tcllib/files/modules/math/symdiff.md) Symbolic differentiation for Tcl + + + [math::combinatorics](tcllib/files/modules/math/combinatorics.md) Combinatorial functions in the Tcl Math Library + + + [math::complexnumbers](tcllib/files/modules/math/qcomplex.md) Straightforward complex number package + + + [math::constants](tcllib/files/modules/math/constants.md) Mathematical and numerical constants + + + [math::decimal](tcllib/files/modules/math/decimal.md) General decimal arithmetic + + + [math::exact](tcllib/files/modules/math/exact.md) Exact Real Arithmetic + + + [math::fourier](tcllib/files/modules/math/fourier.md) Discrete and fast fourier transforms + + + [math::fuzzy](tcllib/files/modules/math/fuzzy.md) Fuzzy comparison of floating-point numbers + + + [math::geometry](tcllib/files/modules/math/math_geometry.md) Geometrical computations + + + [math::interpolate](tcllib/files/modules/math/interpolate.md) Interpolation routines + + + [math::linearalgebra](tcllib/files/modules/math/linalg.md) Linear Algebra + + + [math::numtheory](tcllib/files/modules/math/numtheory.md) Number Theory + + + [math::optimize](tcllib/files/modules/math/optimize.md) Optimisation routines + + + [math::PCA](tcllib/files/modules/math/pca.md) Package for Principal Component Analysis + + + [math::polynomials](tcllib/files/modules/math/polynomials.md) Polynomial functions + + + [math::rationalfunctions](tcllib/files/modules/math/rational_funcs.md) Polynomial functions + + + [math::roman](tcllib/files/modules/math/roman.md) Tools for creating and manipulating roman numerals + + + [math::special](tcllib/files/modules/math/special.md) Special mathematical functions + + + [math::statistics](tcllib/files/modules/math/statistics.md) Basic statistical functions and procedures + + + [math::trig](tcllib/files/modules/math/trig.md) Trigonometric anf hyperbolic functions + + + [tclrep/machineparameters](tcllib/files/modules/math/machineparameters.md) Compute double precision machine parameters. + + * [md4]() + + + [md4](tcllib/files/modules/md4/md4.md) MD4 Message-Digest Algorithm + + * [md5]() + + + [md5](tcllib/files/modules/md5/md5.md) MD5 Message-Digest Algorithm + + * [md5crypt]() + + + [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) MD5-based password encryption + + * [mime]() + + + [mime](tcllib/files/modules/mime/mime.md) Manipulation of MIME body parts + + + [smtp](tcllib/files/modules/mime/smtp.md) Client-side tcl implementation of the smtp protocol + + * [multiplexer]() + + + [multiplexer](tcllib/files/modules/multiplexer/multiplexer.md) One-to-many communication with sockets. + + * [namespacex]() + + + [namespacex](tcllib/files/modules/namespacex/namespacex.md) Namespace utility commands + + * [ncgi]() + + + [ncgi](tcllib/files/modules/ncgi/ncgi.md) Procedures to manipulate CGI values. + + * [nettool]() + + + [nettool](tcllib/files/modules/nettool/nettool.md) Tools for networked applications + + * [nmea]() + + + [nmea](tcllib/files/modules/nmea/nmea.md) Process NMEA data + + * [nns]() + + + [nameserv](tcllib/files/modules/nns/nns_client.md) Name service facility, Client + + + [nameserv::auto](tcllib/files/modules/nns/nns_auto.md) Name service facility, Client Extension + + + [nameserv::common](tcllib/files/modules/nns/nns_common.md) Name service facility, shared definitions + + + [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md) Name service facility, client/server protocol + + + [nameserv::server](tcllib/files/modules/nns/nns_server.md) Name service facility, Server + + + [nns_intro](tcllib/files/modules/nns/nns_intro.md) Name service facility, introduction + + * [nntp]() + + + [nntp](tcllib/files/modules/nntp/nntp.md) Tcl client for the NNTP protocol + + * [ntp]() + + + [ntp_time](tcllib/files/modules/ntp/ntp_time.md) Tcl Time Service Client + + * [oauth]() + + + [oauth](tcllib/files/modules/oauth/oauth.md) oauth API base signature + + * [oometa]() + + + [oometa](tcllib/files/modules/oometa/oometa.md) oo::meta A data registry for classess + + * [ooutil]() + + + [oo::util](tcllib/files/modules/ooutil/ooutil.md) Utility commands for TclOO + + * [otp]() + + + [otp](tcllib/files/modules/otp/otp.md) One-Time Passwords + + * [page]() + + + [page_intro](tcllib/files/modules/page/page_intro.md) page introduction + + + [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) page plugin manager + + + [page_util_flow](tcllib/files/modules/page/page_util_flow.md) page dataflow/treewalker utility + + + [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) page AST normalization, LEMON + + + [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) page AST normalization, PEG + + + [page_util_peg](tcllib/files/modules/page/page_util_peg.md) page PEG transformation utilities + + + [page_util_quote](tcllib/files/modules/page/page_util_quote.md) page character quoting utilities + + * [pki]() + + + [pki](tcllib/files/modules/pki/pki.md) Implementation of the public key cipher + + * [pluginmgr]() + + + [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr.md) Manage a plugin + + * [png]() + + + [png](tcllib/files/modules/png/png.md) PNG querying and manipulation of meta data + + * [pop3]() + + + [pop3](tcllib/files/modules/pop3/pop3.md) Tcl client for POP3 email protocol + + * [pop3d]() + + + [pop3d](tcllib/files/modules/pop3d/pop3d.md) Tcl POP3 server implementation + + + [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) Simple mailbox database for pop3d + + + [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md) Simple user database for pop3d + + * [practcl]() + + + [practcl](tcllib/files/modules/practcl/practcl.md) The Practcl Module + + * [processman]() + + + [processman](tcllib/files/modules/processman/processman.md) Tool for automating the period callback of commands + + * [profiler]() + + + [profiler](tcllib/files/modules/profiler/profiler.md) Tcl source code profiler + + * [pt]() + + + [pt::ast](tcllib/files/modules/pt/pt_astree.md) Abstract Syntax Tree Serialization + + + [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) C/PARAM, Canned configuration, Critcl + + + [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) C/PARAM, Canned configuration, TEA + + + [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) The JSON Grammar Exchange Format + + + [pt::param](tcllib/files/modules/pt/pt_param.md) PackRat Machine Specification + + + [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) Parsing Expression Serialization + + + [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) Parsing Expression Utilities + + + [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) Parsing Expression Grammar Serialization + + + [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) PEG Storage + + + [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) PEG Storage. Canned PEG grammar specification + + + [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) PEG Export + + + [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) PEG Export Plugin. Write CONTAINER format + + + [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) PEG Export Plugin. Write JSON format + + + [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) PEG Export Plugin. Write PEG format + + + [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) PEG Conversion. From CONTAINER format + + + [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) PEG Conversion. Read JSON format + + + [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) PEG Conversion. Read PEG format + + + [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) PEG Import + + + [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) PEG Import Plugin. From CONTAINER format + + + [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) PEG Import Plugin. Read JSON format + + + [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) PEG Import Plugin. Read PEG format + + + [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) Interpreter for parsing expression grammars + + + [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) PEG Conversion. Write CONTAINER format + + + [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) PEG Conversion. Write CPARAM format + + + [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) PEG Conversion. Write JSON format + + + [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) PEG Conversion. Write PARAM format + + + [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) PEG Conversion. Write PEG format + + + [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) PEG Conversion. Write TCLPARAM format + + + [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) PEG Language Tutorial + + + [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) Introduction to Parsing Expression Grammars + + + [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) Parser Generator + + + [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) Parsing Runtime Support, PARAM based + + + [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) Tcl/PARAM, Canned configuration, NX + + + [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) Tcl/PARAM, Canned configuration, Snit + + + [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) Tcl/PARAM, Canned configuration, Tcloo + + + [pt::util](tcllib/files/modules/pt/pt_util.md) General utilities + + + [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) Parser Tools Export API + + + [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) Parser Tools Import API + + + [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) Introduction to Parser Tools + + + [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) Parser Tools PEG Parser + + + [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) Parser API + + + [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md) Parser Tools PE Grammar Utility Operations + + * [rc4]() + + + [rc4](tcllib/files/modules/rc4/rc4.md) Implementation of the RC4 stream cipher + + * [rcs]() + + + [rcs](tcllib/files/modules/rcs/rcs.md) RCS low level utilities + + * [report]() + + + [report](tcllib/files/modules/report/report.md) Create and manipulate report objects + + * [rest]() + + + [rest](tcllib/files/modules/rest/rest.md) define REST web APIs and call them inline or asychronously + + * [ripemd]() + + + [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) RIPEMD-128 Message-Digest Algorithm + + + [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) RIPEMD-160 Message-Digest Algorithm + + * [sasl]() + + + [SASL](tcllib/files/modules/sasl/sasl.md) Implementation of SASL mechanisms for Tcl + + + [SASL::NTLM](tcllib/files/modules/sasl/ntlm.md) Implementation of SASL NTLM mechanism for Tcl + + + [SASL::SCRAM](tcllib/files/modules/sasl/scram.md) Implementation of SASL SCRAM mechanism for Tcl + + + [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md) Implementation of SASL NTLM mechanism for Tcl + + * [sha1]() + + + [sha1](tcllib/files/modules/sha1/sha1.md) SHA1 Message-Digest Algorithm + + + [sha256](tcllib/files/modules/sha1/sha256.md) SHA256 Message-Digest Algorithm + + * [simulation]() + + + [simulation::annealing](tcllib/files/modules/simulation/annealing.md) Simulated annealing + + + [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md) Monte Carlo simulations + + + [simulation::random](tcllib/files/modules/simulation/simulation_random.md) Pseudo-random number generators + + * [smtpd]() + + + [smtpd](tcllib/files/modules/smtpd/smtpd.md) Tcl SMTP server implementation + + * [snit]() + + + [snit](tcllib/files/modules/snit/snit.md) Snit's Not Incr Tcl + + + [snitfaq](tcllib/files/modules/snit/snitfaq.md) Snit Frequently Asked Questions + + * [soundex]() + + + [soundex](tcllib/files/modules/soundex/soundex.md) Soundex + + * [stooop]() + + + [stooop](tcllib/files/modules/stooop/stooop.md) Object oriented extension. + + + [switched](tcllib/files/modules/stooop/switched.md) switch/option management. + + * [string]() + + + [string::token](tcllib/files/modules/string/token.md) Regex based iterative lexing + + + [string::token::shell](tcllib/files/modules/string/token_shell.md) Parsing of shell command line + + * [stringprep]() + + + [stringprep](tcllib/files/modules/stringprep/stringprep.md) Implementation of stringprep + + + [stringprep::data](tcllib/files/modules/stringprep/stringprep_data.md) stringprep data tables, generated, internal + + + [unicode](tcllib/files/modules/stringprep/unicode.md) Implementation of Unicode normalization + + + [unicode::data](tcllib/files/modules/stringprep/unicode_data.md) unicode data tables, generated, internal + + * [struct]() + + + [struct::disjointset](tcllib/files/modules/struct/disjointset.md) Disjoint set data structure + + + [struct::graph](tcllib/files/modules/struct/graph.md) Create and manipulate directed graph objects + + + [struct::graph::op](tcllib/files/modules/struct/graphops.md) Operation for (un)directed graph objects + + + [struct::graph_v1](tcllib/files/modules/struct/graph1.md) Create and manipulate directed graph objects + + + [struct::list](tcllib/files/modules/struct/struct_list.md) Procedures for manipulating lists + + + [struct::matrix](tcllib/files/modules/struct/matrix.md) Create and manipulate matrix objects + + + [struct::matrix_v1](tcllib/files/modules/struct/matrix1.md) Create and manipulate matrix objects + + + [struct::pool](tcllib/files/modules/struct/pool.md) Create and manipulate pool objects (of discrete items) + + + [struct::prioqueue](tcllib/files/modules/struct/prioqueue.md) Create and manipulate prioqueue objects + + + [struct::queue](tcllib/files/modules/struct/queue.md) Create and manipulate queue objects + + + [struct::record](tcllib/files/modules/struct/record.md) Define and create records (similar to 'C' structures) + + + [struct::set](tcllib/files/modules/struct/struct_set.md) Procedures for manipulating sets + + + [struct::skiplist](tcllib/files/modules/struct/skiplist.md) Create and manipulate skiplists + + + [struct::stack](tcllib/files/modules/struct/stack.md) Create and manipulate stack objects + + + [struct::tree](tcllib/files/modules/struct/struct_tree.md) Create and manipulate tree objects + + + [struct::tree_v1](tcllib/files/modules/struct/struct_tree1.md) Create and manipulate tree objects + + * [tar]() + + + [tar](tcllib/files/modules/tar/tar.md) Tar file creation, extraction & manipulation + + * [tepam]() + + + [tepam](tcllib/files/modules/tepam/tepam_introduction.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager + + + [tepam::argument_dialogbox](tcllib/files/modules/tepam/tepam_argument_dialogbox.md) TEPAM argument_dialogbox, reference manual + + + [tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md) TEPAM DOC Generation, reference manual + + + [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md) TEPAM procedure, reference manual + + * [term]() + + + [term](tcllib/files/modules/term/term.md) General terminal control + + + [term::ansi::code](tcllib/files/modules/term/ansi_code.md) Helper for control sequences + + + [term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) ANSI attribute sequences + + + [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) ANSI control sequences + + + [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) Macro sequences + + + [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md) Control operations and queries + + + [term::ansi::send](tcllib/files/modules/term/ansi_send.md) Output of ANSI control sequences to terminals + + + [term::interact::menu](tcllib/files/modules/term/imenu.md) Terminal widget, menu + + + [term::interact::pager](tcllib/files/modules/term/ipager.md) Terminal widget, paging + + + [term::receive](tcllib/files/modules/term/receive.md) General input from terminals + + + [term::receive::bind](tcllib/files/modules/term/term_bind.md) Keyboard dispatch from terminals + + + [term::send](tcllib/files/modules/term/term_send.md) General output to terminals + + * [textutil]() + + + [textutil](tcllib/files/modules/textutil/textutil.md) Procedures to manipulate texts and strings. + + + [textutil::adjust](tcllib/files/modules/textutil/adjust.md) Procedures to adjust, indent, and undent paragraphs + + + [textutil::expander](tcllib/files/modules/textutil/expander.md) Procedures to process templates and expand text. + + + [textutil::repeat](tcllib/files/modules/textutil/repeat.md) Procedures to repeat strings. + + + [textutil::split](tcllib/files/modules/textutil/textutil_split.md) Procedures to split texts + + + [textutil::string](tcllib/files/modules/textutil/textutil_string.md) Procedures to manipulate texts and strings. + + + [textutil::tabify](tcllib/files/modules/textutil/tabify.md) Procedures to (un)tabify strings + + + [textutil::trim](tcllib/files/modules/textutil/trim.md) Procedures to trim strings + + * [tie]() + + + [tie](tcllib/files/modules/tie/tie.md) Array persistence + + + [tie](tcllib/files/modules/tie/tie_std.md) Array persistence, standard data sources + + * [tiff]() + + + [tiff](tcllib/files/modules/tiff/tiff.md) TIFF reading, writing, and querying and manipulation of meta data + + * [tool]() + + + [oo::util](tcllib/files/modules/tool/meta.md) Utility commands for TclOO + + + [tool](tcllib/files/modules/tool/tool.md) TclOO Library (TOOL) Framework + + + [tool::dict_ensemble](tcllib/files/modules/tool/tool_dict_ensemble.md) Dictionary Tools + + * [transfer]() + + + [transfer::connect](tcllib/files/modules/transfer/connect.md) Connection setup + + + [transfer::copy](tcllib/files/modules/transfer/copyops.md) Data transfer foundation + + + [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) Queued transfers + + + [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) Data destination + + + [transfer::data::source](tcllib/files/modules/transfer/dsource.md) Data source + + + [transfer::receiver](tcllib/files/modules/transfer/receiver.md) Data source + + + [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md) Data source + + * [treeql]() + + + [treeql](tcllib/files/modules/treeql/treeql.md) Query tree objects + + * [try]() + + + [throw](tcllib/files/modules/try/tcllib_throw.md) throw - Throw an error exception with a message + + + [try](tcllib/files/modules/try/tcllib_try.md) try - Trap and process errors and exceptions + + * [udpcluster]() + + + [udpcluster](tcllib/files/modules/udpcluster/udpcluster.md) UDP Peer-to-Peer cluster + + * [uev]() + + + [uevent](tcllib/files/modules/uev/uevent.md) User events + + + [uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md) Request merging and deferal to idle time + + * [units]() + + + [units](tcllib/files/modules/units/units.md) unit conversion + + * [uri]() + + + [uri](tcllib/files/modules/uri/uri.md) URI utilities + + + [uri_urn](tcllib/files/modules/uri/urn-scheme.md) URI utilities, URN scheme + + * [uuid]() + + + [uuid](tcllib/files/modules/uuid/uuid.md) UUID generation and comparison + + * [valtype]() + + + [valtype::common](tcllib/files/modules/valtype/valtype_common.md) Validation, common code + + + [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) Validation for AMEX creditcard number + + + [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) Validation for Discover creditcard number + + + [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) Validation for Mastercard creditcard number + + + [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) Validation for VISA creditcard number + + + [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) Validation for EAN13 + + + [valtype::iban](tcllib/files/modules/valtype/iban.md) Validation for IBAN + + + [valtype::imei](tcllib/files/modules/valtype/imei.md) Validation for IMEI + + + [valtype::isbn](tcllib/files/modules/valtype/isbn.md) Validation for ISBN + + + [valtype::luhn](tcllib/files/modules/valtype/luhn.md) Validation for plain number with a LUHN checkdigit + + + [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) Validation for plain number with a LUHN5 checkdigit + + + [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) Validation for USNPI + + + [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md) Validation for plain number with a VERHOEFF checkdigit + + * [virtchannel_base]() + + + [tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) Concatenation channel + + + [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) Facade channel + + + [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) In-memory fifo channel + + + [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) In-memory interconnected fifo channels + + + [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) In-memory channel, half of a fifo2 + + + [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) In-memory channel + + + [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) Null channel + + + [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) Null/Zero channel combination + + + [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) Random channel + + + [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) Standard I/O, unification of stdin and stdout + + + [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) Read-only in-memory channel + + + [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) Textwindow channel + + + [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) In-memory channel using variable for storage + + + [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) Zero channel + + + [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) Utilities for random channels + + * [virtchannel_core]() + + + [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) Basic reflected/virtual channel support + + + [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) Event support for reflected/virtual channels + + + [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md) Basic reflected/virtual channel transform support + + * [virtchannel_transform]() + + + [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) Adler32 transformation + + + [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) Base64 encoding transformation + + + [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) Counter transformation + + + [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) Crc32 transformation + + + [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) Hexadecimal encoding transformation + + + [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) Identity transformation + + + [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) limiting input + + + [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) Observer transformation, stream copy + + + [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) Encryption via one-time pad + + + [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) rot-encryption + + + [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) Space insertation and removal + + + [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md) zlib (de)compression + + * [websocket]() + + + [websocket](tcllib/files/modules/websocket/websocket.md) Tcl implementation of the websocket protocol + + * [wip]() + + + [wip](tcllib/files/modules/wip/wip.md) Word Interpreter + + * [yaml]() + + + [huddle](tcllib/files/modules/yaml/huddle.md) Create and manipulate huddle object + + + [yaml](tcllib/files/modules/yaml/yaml.md) YAML Format Encoder/Decoder + + * [zip]() + + + [zipfile::decode](tcllib/files/modules/zip/decode.md) Access to zip archives + + + [zipfile::encode](tcllib/files/modules/zip/encode.md) Generation of zip archives + + + [zipfile::mkzip](tcllib/files/modules/zip/mkzip.md) Build a zip archive ADDED embedded/md/toc2.md Index: embedded/md/toc2.md ================================================================== --- /dev/null +++ embedded/md/toc2.md @@ -0,0 +1,20 @@ + +[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown') + +# Table Of Contents -- + + - [Applications]() + + * [dtplite](tcllib/files/apps/dtplite.md) Lightweight DocTools Markup Processor + + * [nns](tcllib/files/apps/nns.md) Name service facility, Commandline Client Application + + * [nnsd](tcllib/files/apps/nnsd.md) Name service facility, Commandline Server Application + + * [nnslog](tcllib/files/apps/nnslog.md) Name service facility, Commandline Logging Client Application + + * [page](tcllib/files/apps/page.md) Parser Generator + + * [pt](tcllib/files/apps/pt.md) Parser Tools Application + + * [tcldocstrip](tcllib/files/apps/tcldocstrip.md) Tcl-based Docstrip Processor DELETED embedded/www/image/arch_core_container.png Index: embedded/www/image/arch_core_container.png ================================================================== --- embedded/www/image/arch_core_container.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/image/arch_core_eplugins.png Index: embedded/www/image/arch_core_eplugins.png ================================================================== --- embedded/www/image/arch_core_eplugins.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/image/arch_core_export.png Index: embedded/www/image/arch_core_export.png ================================================================== --- embedded/www/image/arch_core_export.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/image/arch_core_import.png Index: embedded/www/image/arch_core_import.png ================================================================== --- embedded/www/image/arch_core_import.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/image/arch_core_iplugins.png Index: embedded/www/image/arch_core_iplugins.png ================================================================== --- embedded/www/image/arch_core_iplugins.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/image/arch_core_support.png Index: embedded/www/image/arch_core_support.png ================================================================== --- embedded/www/image/arch_core_support.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/image/arch_core_transform.png Index: embedded/www/image/arch_core_transform.png ================================================================== --- embedded/www/image/arch_core_transform.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/image/arch_user_app.png Index: embedded/www/image/arch_user_app.png ================================================================== --- embedded/www/image/arch_user_app.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/image/arch_user_pkg.png Index: embedded/www/image/arch_user_pkg.png ================================================================== --- embedded/www/image/arch_user_pkg.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/image/architecture.png Index: embedded/www/image/architecture.png ================================================================== --- embedded/www/image/architecture.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/image/expr_ast.png Index: embedded/www/image/expr_ast.png ================================================================== --- embedded/www/image/expr_ast.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/image/flow.png Index: embedded/www/image/flow.png ================================================================== --- embedded/www/image/flow.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/image/gen_options.png Index: embedded/www/image/gen_options.png ================================================================== --- embedded/www/image/gen_options.png +++ /dev/null cannot compute difference between binary files DELETED embedded/www/index.html Index: embedded/www/index.html ================================================================== --- embedded/www/index.html +++ /dev/null @@ -1,4439 +0,0 @@ -

- -

[ - Table Of Contents -| Categories -| Modules -| Applications - ]

Keyword Index

- 3 · A · B · C · D · E · F · G · H · I · J · K · L · M · N · O · P · Q · R · S · T · U · V · W · X · Y · Z -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

DELETED embedded/www/tcllib/files/apps/dtplite.html Index: embedded/www/tcllib/files/apps/dtplite.html ================================================================== --- embedded/www/tcllib/files/apps/dtplite.html +++ /dev/null @@ -1,433 +0,0 @@ - -

- -

dtplite(n) 1.0.5 tcllib "Documentation toolbox"

Name

dtplite - Lightweight DocTools Markup Processor

Table Of Contents
Synopsis
Description -
- USE CASES
- COMMAND LINE
- OPTIONS
- FORMATS
- DIRECTORY STRUCTURES
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

dtplite -o output ?options? format inputfile
dtplite validate inputfile
dtplite -o output ?options? format inputdirectory
dtplite -merge -o output ?options? format inputdirectory

Description

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

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

USE CASES

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

Validation of a single document, i.e. checking that it was written in -valid doctools format. This mode can also be used to get a preliminary -version of the formatted output for a single document, for display in -a browser, nroff, etc., allowing proofreading of the formatting.
Generation of the formatted documentation for a single package, -i.e. all the manpages, plus a table of contents and an index of -keywords.
An extension of the previous mode of operation, a method for the easy -generation of one documentation tree for several packages, and -especially of a unified table of contents and keyword index.

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

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

COMMAND LINE

dtplite -o output ?options? format inputfile

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

path output (in)

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

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

(path|handle) format (in)

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

path inputfile (in)

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

dtplite validate inputfile

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

dtplite -o output ?options? format inputdirectory

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

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

dtplite -merge -o output ?options? format inputdirectory

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

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

OPTIONS

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

-exclude string

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

-ext string

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

When used multiple times only the last definition is relevant.

-header file

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

When used multiple times only the last definition is relevant.

-footer file

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

When used multiple times only the last definition is relevant.

-style file

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

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

When used multiple times only the last definition is relevant.

-toc path

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

When used multiple times only the last definition is relevant.

-pre+toc label path|text

-post+toc label path|text

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

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

-nav label url

-prenav label url

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

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

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

-postnav label url

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

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

FORMATS

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

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

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

nroff: The processor generates *roff output, the standard format for unix -manpages.
html: The processor generates HTML output, for usage in and display by web -browsers. This engine is currently the only one providing the various -engine parameters required for the additional customaization of the -output.
tmml: The processor generates TMML output, the Tcl Manpage Markup Language, -a derivative of XML.
latex: The processor generates LaTeX output.
wiki: The processor generates Wiki markup as understood by wikit.
list: The processor extracts the information provided by manpage_begin. -This format is used internally to extract the meta data from which -both table of contents and keyword index are derived from.
null: The processor does not generate any output. This is equivalent to -validate.

DIRECTORY STRUCTURES

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

[2]

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

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

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

-    inputdirectory/path/to/FOO
-

[3]

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

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

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

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

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

Bugs, Ideas, Feedback

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

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

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

Keywords

HTML, TMML, conversion, docidx, doctoc, doctools, manpage, markup, nroff

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/apps/nns.html Index: embedded/www/tcllib/files/apps/nns.html ================================================================== --- embedded/www/tcllib/files/apps/nns.html +++ /dev/null @@ -1,235 +0,0 @@ - -

- -

nns(n) 1.1 tcllib "Name service facility"

Name

nns - Name service facility, Commandline Client Application

Table Of Contents
Synopsis
Description -
- USE CASES
- COMMAND LINE
- OPTIONS
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

nns bind ?-host host? ?-port port? name data
nns search ?-host host? ?-port port? ?-continuous? ?pattern?
nns ident ?-host host? ?-port port?
nns who

Description

Please read Name service facility, introduction first.

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

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

USE CASES

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

Registration of a name/data pair in the name service.
Searching the name service for entries matching a glob pattern.

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

COMMAND LINE

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

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

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

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

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

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

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

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

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

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

nns who

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

OPTIONS

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

-host name|ipaddress: If this option is not specified it defaults to localhost. It -specifies the name or ip-address of the host the name service to talk -to is running on.
-port number: If this option is not specified it defaults to 38573. It -specifies the TCP port the name service to talk to is listening on for -requests.

Bugs, Ideas, Feedback

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

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

Keywords

application, client, name service

Category

Networking

Copyright

DELETED embedded/www/tcllib/files/apps/nnsd.html Index: embedded/www/tcllib/files/apps/nnsd.html ================================================================== --- embedded/www/tcllib/files/apps/nnsd.html +++ /dev/null @@ -1,203 +0,0 @@ - -

- -

nnsd(n) 1.0.1 tcllib "Name service facility"

Name

nnsd - Name service facility, Commandline Server Application

Table Of Contents
Synopsis
Description -
- USE CASES
- COMMAND LINE
- OPTIONS
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

nnsd ?-localonly flag? ?-port port?

Description

Please read Name service facility, introduction first.

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

USE CASES

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

Run a nano name service on some host.

COMMAND LINE

nnsd ?-localonly flag? ?-port port?

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

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

OPTIONS

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

-localonly bool: If this option is not specified it defaults to true, i.e. -acceptance of only local connections. The server will accept remote -connections, i.e. connections from other hosts, if and only if this -option is configured to false.
-port number: If this option is not specified it defaults to 38573. It -specifies the TCP port the server has to listen on for requests.

Bugs, Ideas, Feedback

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

Keywords

application, name service, server

Category

Networking

Copyright

DELETED embedded/www/tcllib/files/apps/nnslog.html Index: embedded/www/tcllib/files/apps/nnslog.html ================================================================== --- embedded/www/tcllib/files/apps/nnslog.html +++ /dev/null @@ -1,206 +0,0 @@ - -

- -

nnslog(n) 1.0 tcllib "Name service facility"

Name

nnslog - Name service facility, Commandline Logging Client Application

Table Of Contents
Synopsis
Description -
- USE CASES
- COMMAND LINE
- OPTIONS
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

nnslog ?-host host? ?-port port?

Description

Please read Name service facility, introduction first.

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

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

USE CASES

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

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

COMMAND LINE

nnslog ?-host host? ?-port port?

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

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

OPTIONS

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

-host name|ipaddress: If this option is not specified it defaults to localhost. It -specifies the name or ip-address of the host the name service to talk -to is running on.
-port number: If this option is not specified it defaults to 38573. It -specifies the TCP port the name service to talk to is listening on for -requests.

Bugs, Ideas, Feedback

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

Keywords

application, client, name service

Category

Networking

Copyright

DELETED embedded/www/tcllib/files/apps/page.html Index: embedded/www/tcllib/files/apps/page.html ================================================================== --- embedded/www/tcllib/files/apps/page.html +++ /dev/null @@ -1,473 +0,0 @@ - -

- -

page(n) 1.0 tcllib "Development Tools"

Name

page - Parser Generator

Table Of Contents
Synopsis
Description -
- COMMAND LINE
- OPERATION
- OPTIONS
- PLUGINS
- PLUGIN LOCATIONS
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

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

Description

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

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

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

COMMAND LINE

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

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

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

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

path input (in)

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

path output (in)

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

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

If the argument is missing - is assumed.

OPERATION

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

OPTIONS

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

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

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

-c peg

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

--help

-h

-?

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

--version

-V

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

-P

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

-T

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

-D

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

-r parser

-rd parser

--reader parser

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

-w generator

-wr generator

--writer generator

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

-t process

-tr process

--transform process

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

-a

--append

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

-p

--prepend

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

--reset

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

-c file

--configuration file

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

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

PLUGINS

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

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

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

-c name

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

We have one predefined plugin:

peg

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

-	--reset
-	--append
-	--reader    peg
-	--transform reach
-	--transform use
-	--writer    me
-

-r name

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

We have five predefined plugins:

peg: Interprets the input as a parsing expression grammar (PEG) and -generates a tree representation for it. Both the syntax of PEGs and -the structure of the tree representation are explained in their own -manpages.
hb: Interprets the input as Tcl code as generated by the writer plugin -hb and generates its tree representation.
ser: Interprets the input as the serialization of a PEG, as generated by -the writer plugin ser, using the package -grammar::peg.
lemon: Interprets the input as a grammar specification as understood by -Richard Hipp's LEMON parser generator and generates a tree -representation for it. Both the input syntax and the structure of the -tree representation are explained in their own manpages.
treeser: Interprets the input as the serialization of a -struct::tree. It is validated as such, -but nothing else. It is not assumed to -be the tree representation of a grammar.

-w name

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

We have eight predefined plugins:

identity: Simply writes the incoming data as it is, without making any -changes. This is good for inspecting the raw result of a reader or -transformation.
null: Generates nothing, and ignores the incoming data structure.
tree: Assumes that the incoming data structure is a struct::tree -and generates an indented textual representation of all nodes, their -parental relationships, and their attribute information.
peg: Assumes that the incoming data structure is a tree representation of a -PEG or other other grammar and writes it out as a PEG. The -result is nicely formatted and partially simplified (strings as -sequences of characters). A pretty printer in essence, but can also be -used to obtain a canonical representation of the input grammar.
tpc: Assumes that the incoming data structure is a tree representation of a -PEG or other other grammar and writes out Tcl code defining a -package which defines a grammar::peg object containing the -grammar when it is loaded into an interpreter.
hb: This is like the writer plugin tpc, but it writes only the -statements which define stat expression and grammar rules. The code -making the result a package is left out.
ser: Assumes that the incoming data structure is a tree representation of a -PEG or other other grammar, transforms it internally into a -grammar::peg object and writes out its serialization.
me: Assumes that the incoming data structure is a tree representation of a -PEG or other other grammar and writes out Tcl code defining a -package which implements a memoizing recursive descent parser based on -the match engine (ME) provided by the package grammar::mengine.

-t name

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

We have two predefined plugins:

reach: Assumes that the incoming data structure is a tree representation of a -PEG or other other grammar. It determines which nonterminal -symbols and rules are reachable from start-symbol/expression. All -nonterminal symbols which were not reached are removed.
use: Assumes that the incoming data structure is a tree representation of a -PEG or other other grammar. It determines which nonterminal -symbols and rules are able to generate a finite sequences of -terminal symbols (in the sense for a Context Free Grammar). All -nonterminal symbols which were not deemed useful in this sense are -removed.

PLUGIN LOCATIONS

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

The directory "~/.page/plugin"
The environment variable PAGE_PLUGINS
The registry entry HKEY_LOCAL_MACHINE\SOFTWARE\PAGE\PLUGINS
The registry entry HKEY_CURRENT_USER\SOFTWARE\PAGE\PLUGINS

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

The directory "~/.page/plugin/<TYPE>"
The environment variable PAGE_<TYPE>_PLUGINS
The registry entry HKEY_LOCAL_MACHINE\SOFTWARE\PAGE\<TYPE>\PLUGINS
The registry entry HKEY_CURRENT_USER\SOFTWARE\PAGE\<TYPE>\PLUGINS

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

reader
writer
transform
config

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

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

Bugs, Ideas, Feedback

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

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

Keywords

parser generator, text processing

Category

Page Parser Generator

Copyright

DELETED embedded/www/tcllib/files/apps/pt.html Index: embedded/www/tcllib/files/apps/pt.html ================================================================== --- embedded/www/tcllib/files/apps/pt.html +++ /dev/null @@ -1,686 +0,0 @@ - -

- -

pt(n) 1 tcllib "Parser Tools"

Name

pt - Parser Tools Application

Table Of Contents
Synopsis
Description
Command Line
PEG Specification Language
JSON Grammar Exchange
C Parser Embedded In Tcl
C Parser
Snit Parser
TclOO Parser
Grammar Container
Example
Internals
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.5

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

Description

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

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

It resides in the User Application Layer of Parser Tools.

arch_user_app

Command Line

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

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

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

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

c: A resultformat. See section C Parser.
container: A resultformat. See section Grammar Container.
critcl: A resultformat. See section C Parser Embedded In Tcl.
json: A input- and resultformat. See section JSON Grammar Exchange.
oo: A resultformat. See section TclOO Parser.
peg: A input- and resultformat. See section PEG Specification Language.
snit: A resultformat. See section Snit Parser.

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

The created parsers fall into three categories:

gen_options

Specialized parsers implemented in C

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

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

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

Specialized parsers implemented in Tcl

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

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

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

Interpreted parsing implemented in Tcl

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

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

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

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

PEG Specification Language

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

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

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

-file string

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

-name string

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

-user string

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

-template string

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

@user@: To be replaced with the value of the option -user.
@format@: To be replaced with the the constant PEG.
@file@: To be replaced with the value of the option -file.
@name@: To be replaced with the value of the option -name.
@code@: To be replaced with the generated text.

JSON Grammar Exchange

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

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

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

-file string

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

-name string

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

-user string

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

-indented boolean

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

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

-aligned boolean

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

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

C Parser Embedded In Tcl

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

This result-format supports the following options:

-file string

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

-name string

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

-user string

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

-class string

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

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

-package string

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

-version string

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

C Parser

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

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

This result-format supports the following options:

-file string

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

-name string

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

-user string

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

-template string

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

@user@: To be replaced with the value of the option -user.
@format@: To be replaced with the the constant C/PARAM.
@file@: To be replaced with the value of the option -file.
@name@: To be replaced with the value of the option -name.
@code@: To be replaced with the generated Tcl code.

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

@statedecl@: To be replaced with the value of the option state-decl.
@stateref@: To be replaced with the value of the option state-ref.
@strings@: To be replaced with the value of the option string-varname.
@self@: To be replaced with the value of the option self-command.
@def@: To be replaced with the value of the option fun-qualifier.
@ns@: To be replaced with the value of the option namespace.
@main@: To be replaced with the value of the option main.
@prelude@: To be replaced with the value of the option prelude.

-state-decl string

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

-state-ref string

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

-self-command string

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

-fun-qualifier string

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

-namespace string

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

-main string

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

-string-varname string

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

-prelude string

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

-indent integer

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

-comments boolean

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

Snit Parser

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

This result-format supports the following options:

-file string: The value of this option is the name of the file or other entity from -which the grammar came, for which the command is run. The default -value is unknown.
-name string: The value of this option is the name of the grammar we are processing. -The default value is a_pe_grammar.
-user string: The value of this option is the name of the user for which the command -is run. The default value is unknown.
-class string: The value of this option is the name of the class to generate, without -leading colons. Note, it serves double-duty as the name of the package -to generate too, if option -package is not specified, see below. -The default value is CLASS, applying if neither option --class nor -package were specified.
-package string: The value of this option is the name of the package to generate, without -leading colons. Note, it serves double-duty as the name of the class -to generate too, if option -class is not specified, see above. -The default value is PACKAGE, applying if neither option --package nor -class were specified.
-version string: The value of this option is the version of the package to generate. -The default value is 1.

TclOO Parser

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

This result-format supports the following options:

-file string: The value of this option is the name of the file or other entity from -which the grammar came, for which the command is run. The default -value is unknown.
-name string: The value of this option is the name of the grammar we are processing. -The default value is a_pe_grammar.
-user string: The value of this option is the name of the user for which the command -is run. The default value is unknown.
-class string: The value of this option is the name of the class to generate, without -leading colons. Note, it serves double-duty as the name of the package -to generate too, if option -package is not specified, see below. -The default value is CLASS, applying if neither option --class nor -package were specified.
-package string: The value of this option is the name of the package to generate, without -leading colons. Note, it serves double-duty as the name of the class -to generate too, if option -class is not specified, see above. -The default value is PACKAGE, applying if neither option --package nor -class were specified.
-version string: The value of this option is the version of the package to generate. -The default value is 1.

Grammar Container

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

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

This result-format supports the following options:

-file string

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

-name string

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

-user string

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

-mode bulk|incremental

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

bulk

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

This mode is the default.

incremental

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

-template string

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

@user@: To be replaced with the value of the option -user.
@format@: To be replaced with the the constant CONTAINER.
@file@: To be replaced with the value of the option -file.
@name@: To be replaced with the value of the option -name.
@mode@: To be replaced with the value of the option -mode.
@code@: To be replaced with the generated code.

Example

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

flow

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

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

From this we create a snit-based parser -via

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

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

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

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

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

assuming that the input file and channel contained the text

 120+5

A more graphical representation of the tree would be

expr_ast

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

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

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

Internals

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

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

Bugs, Ideas, Feedback

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

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

Keywords

EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer

Category

Parsing and Grammars

Copyright

DELETED embedded/www/tcllib/files/apps/tcldocstrip.html Index: embedded/www/tcllib/files/apps/tcldocstrip.html ================================================================== --- embedded/www/tcllib/files/apps/tcldocstrip.html +++ /dev/null @@ -1,276 +0,0 @@ - -

- -

tcldocstrip(n) 1.0 tcllib "Textprocessing toolbox"

Name

tcldocstrip - Tcl-based Docstrip Processor

Table Of Contents
Synopsis
Description -
- USE CASES
- COMMAND LINE
- OPTIONS
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

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

Description

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

tcldocstrip is based upon the package docstrip.

USE CASES

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

Conversion of a single input file according to the listed guards into -the stripped output. This handles the most simple case of a set of -guards specifying a single document found in a single input file.
Stitching, or the assembly of an output from several sets of guards, -in a specific order, and possibly from different files. This is the -second common case. One document spread over several inputs, and/or -spread over different guard sets.
Extraction and listing of all the unique guard expressions and guards -used within a document to help a person which did not author the -document in question in familiarizing itself with it.

COMMAND LINE

tcldocstrip output ?options? input ?guards?

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

path output (in)

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

path inputfile (in)

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

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

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

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

tcldocstrip -guards input

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

OPTIONS

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

-metaprefix string

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

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

-onerror mode

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

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

ignore: Just ignore the error; continue as if nothing happened.
puts: Write an error message to stderr, then continue processing.
throw: Throw an error. ::errorCode is set to a list whose first element -is DOCSTRIP, second element is the type of error, and third -element is the line number where the error is detected. This is the -default.

-trimlines bool

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

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

-preamble text

-postamble text

-nopreamble

-nopostamble

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

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

Bugs, Ideas, Feedback

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

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

Keywords

.dtx, LaTeX, conversion, docstrip, documentation, literate programming, markup, source

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/aes/aes.html Index: embedded/www/tcllib/files/modules/aes/aes.html ================================================================== --- embedded/www/tcllib/files/modules/aes/aes.html +++ /dev/null @@ -1,265 +0,0 @@ - -

- -

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

Name

aes - Implementation of the AES block cipher

Table Of Contents
Synopsis
Description
COMMANDS
PROGRAMMING INTERFACE
MODES OF OPERATION
EXAMPLES
REFERENCES
AUTHORS
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.5
package require aes ?1.2.1?

::aes::aes ?-mode [ecb|cbc]? ?-dir [encrypt|decrypt]? -key keydata ?-iv vector? ?-hex? ?-out channel? ?-chunksize size? [ -in channel | ?--? data ]
::aes::Init mode keydata iv
::aes::Encrypt Key data
::aes::Decrypt Key data
::aes::Reset Key iv
::aes::Final Key

Description

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

COMMANDS

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

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

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

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

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

PROGRAMMING INTERFACE

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

::aes::Init mode keydata iv: Construct a new AES key schedule using the specified key data and the -given initialization vector. The initialization vector is not used -with ECB mode but is important for CBC mode. -See MODES OF OPERATION for details about cipher modes.
::aes::Encrypt Key data: Use a prepared key acquired by calling Init to encrypt the -provided data. The data argument should be a binary array that is a -multiple of the AES block size of 16 bytes. The result is a binary -array the same size as the input of encrypted data.
::aes::Decrypt Key data: Decipher data using the key. Note that the same key may be used to -encrypt and decrypt data provided that the initialization vector is -reset appropriately for CBC mode.
::aes::Reset Key iv: Reset the initialization vector. This permits the programmer to re-use -a key and avoid the cost of re-generating the key schedule where the -same key data is being used multiple times.
::aes::Final Key: This should be called to clean up resources associated with Key. -Once this function has been called the key may not be used again.

MODES OF OPERATION

Electronic Code Book (ECB): ECB is the basic mode of all block ciphers. Each block is encrypted -independently and so identical plain text will produce identical -output when encrypted with the same key. Any encryption errors will -only affect a single block however this is vulnerable to known -plaintext attacks.
Cipher Block Chaining (CBC): CBC mode uses the output of the last block encryption to affect the -current block. An initialization vector of the same size as the cipher -block size is used to handle the first block. The initialization -vector should be chosen randomly and transmitted as the first block of -the output. Errors in encryption affect the current block and the next -block after which the cipher will correct itself. CBC is the most -commonly used mode in software encryption. This is the default mode -of operation for this module.

EXAMPLES

-% set nil_block [string repeat \\0 16]
-% aes::aes -hex -mode cbc -dir encrypt -key $nil_block $nil_block
-66e94bd4ef8a2c3b884cfa59ca342b2e
-

-set Key [aes::Init cbc $sixteen_bytes_key_data $sixteen_byte_iv]
-append ciphertext [aes::Encrypt $Key $plaintext]
-append ciphertext [aes::Encrypt $Key $additional_plaintext]
-aes::Final $Key
-

REFERENCES

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

AUTHORS

Thorsten Schloermann, Pat Thoyts

Bugs, Ideas, Feedback

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

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

Keywords

aes, block cipher, data integrity, encryption, security

Category

Hashes, checksums, and encryption

Copyright

DELETED embedded/www/tcllib/files/modules/amazon-s3/S3.html Index: embedded/www/tcllib/files/modules/amazon-s3/S3.html ================================================================== --- embedded/www/tcllib/files/modules/amazon-s3/S3.html +++ /dev/null @@ -1,1286 +0,0 @@ - -

- -

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

Name

S3 - Amazon S3 Web Service Interface

Table Of Contents
Synopsis
Description
ERROR REPORTING
COMMANDS
LOW LEVEL COMMANDS
HIGH LEVEL COMMANDS
LIMITATIONS
USAGE SUGGESTIONS
FUTURE DEVELOPMENTS
TLS Security Considerations
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

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

S3::Configure ?-reset boolean? ?-retries integer? ?-accesskeyid idstring? ?-secretaccesskey idstring? ?-service-access-point FQDN? ?-use-tls boolean? ?-default-compare always|never|exists|missing|newer|date|checksum|different? ?-default-separator string? ?-default-acl private|public-read|public-read-write|authenticated-read|keep|calc? ?-default-bucket bucketname?
S3::SuggestBucket ?name?
S3::REST dict
S3::ListAllMyBuckets ?-blocking boolean? ?-parse-xml xmlstring? ?-result-type REST|xml|pxml|dict|names|owner?
S3::PutBucket ?-bucket bucketname? ?-blocking boolean? ?-acl {}|private|public-read|public-read-write|authenticated-read?
S3::DeleteBucket ?-bucket bucketname? ?-blocking boolean?
S3::GetBucket ?-bucket bucketname? ?-blocking boolean? ?-parse-xml xmlstring? ?-max-count integer? ?-prefix prefixstring? ?-delimiter delimiterstring? ?-result-type REST|xml|pxml|names|dict?
S3::Put ?-bucket bucketname? -resource resourcename ?-blocking boolean? ?-file filename? ?-content contentstring? ?-acl private|public-read|public-read-write|authenticated-read|calc|keep? ?-content-type contenttypestring? ?-x-amz-meta-* metadatatext? ?-compare comparemode?
S3::Get ?-bucket bucketname? -resource resourcename ?-blocking boolean? ?-compare comparemode? ?-file filename? ?-content contentvarname? ?-timestamp aws|now? ?-headers headervarname?
S3::Head ?-bucket bucketname? -resource resourcename ?-blocking boolean? ?-dict dictvarname? ?-headers headersvarname? ?-status statusvarname?
S3::GetAcl ?-blocking boolean? ?-bucket bucketname? -resource resourcename ?-result-type REST|xml|pxml?
S3::PutAcl ?-blocking boolean? ?-bucket bucketname? -resource resourcename ?-acl new-acl?
S3::Delete ?-bucket bucketname? -resource resourcename ?-blocking boolean? ?-status statusvar?
S3::Push ?-bucket bucketname? -directory directoryname ?-prefix prefixstring? ?-compare comparemode? ?-x-amz-meta-* metastring? ?-acl aclcode? ?-delete boolean? ?-error throw|break|continue? ?-progress scriptprefix?
S3::Pull ?-bucket bucketname? -directory directoryname ?-prefix prefixstring? ?-blocking boolean? ?-compare comparemode? ?-delete boolean? ?-timestamp aws|now? ?-error throw|break|continue? ?-progress scriptprefix?
S3::Toss ?-bucket bucketname? -prefix prefixstring ?-blocking boolean? ?-error throw|break|continue? ?-progress scriptprefix?

Description

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

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

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

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

ERROR REPORTING

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

usage: The usage of the package is incorrect. For example, -a command has been invoked which requires the library to be configured -before the library has been configured, or an invalid combination of -options has been specified. The third element of $errorCode supplies -the name of the parameter that was wrong. The fourth usually provides -the arguments that were actually supplied to the throwing proc, unless -the usage error isn't confined to a single proc.
local: Something happened on the local system which threw -an error. For example, a request to upload or download a file was made -and the file permissions denied that sort of access. The third element -of $errorCode is the original $errorCode.
socket: Something happened with the socket. It closed -prematurely, or some other condition of failure-to-communicate-with-Amazon -was detected. The third element of $errorCode is the original $errorCode, -or sometimes the message from fcopy, or ...?
remote: The Amazon web service returned an error code outside -the 2xx range in the HTTP header. In other words, everything went as -documented, except this particular case was documented not to work. -The third element is the dictionary returned from ::S3::REST. -Note that S3::REST itself never throws this error, but just returns -the dictionary. Most of the higher-level commands throw for convenience, -unless an argument indicates they should not. If something is documented -as "not throwing an S3 remote error", it means a status return is set -rather than throwing an error if Amazon returns a non-2XX HTTP result code.
notyet: The user obeyed the documentation, but the author -has not yet gotten around to implementing this feature. (Right now, -only TLS support and sophisticated permissions fall into this category, -as well as the S3::Acl command.)
xml: The service has returned invalid XML, or XML whose -schema is unexpected. For the high-level commands that accept -service XML as input for parsing, this may also be thrown.

COMMANDS

This package provides several separate levels of complexity.

The lowest level simply takes arguments to be sent to the service, -sends them, retrieves the result, and provides it to the caller. -Note: This layer allows both synchronous and event-driven -processing. It depends on the MD5 and SHA1 and base64 packages -from Tcllib (available at http://core.tcl.tk/tcllib/). -Note that S3::Configure is required for S3::REST to -work due to the authentication portion, so we put that in the "lowest level."
The next layer parses the results of calls, allowing for functionality -such as uploading only changed files, synchronizing directories, -and so on. This layer depends on the TclXML package as well as the -included xsxp package. These packages are package required when -these more-sophisticated routines are called, so nothing breaks if -they are not correctly installed.
Also included is a separate program that uses the library. -It provides code to parse $argv0 and $argv from the -command line, allowing invocation as a tclkit, etc. -(Not yet implmented.)
Another separate program provides a GUI interface allowing drag-and-drop -and other such functionality. (Not yet implemented.)
Also built on this package is the OddJob program. It is -a separate program designed to allow distribution of -computational work units over Amazon's Elastic Compute -Cloud web service.

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

LOW LEVEL COMMANDS

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

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

The following options are accepted:

-reset boolean: By default, false. If true, any previous changes and any changes on the -same call before the reset option will be returned to default values.
-retries integer: Default value is 3. -If Amazon returns a 500 error, a retry after an exponential -backoff delay will be tried this many times before finally -throwing the 500 error. This applies to each call to S3::REST -from the higher-level commands, but not to S3::REST itself. -That is, S3::REST will always return httpstatus 500 if that's -what it receives. Functions like S3::Put will retry the PUT call, -and will also retry the GET and HEAD calls used to do content comparison. -Changing this to 0 will prevent retries and their associated delays. -In addition, socket errors (i.e., errors whose errorCode starts with -"S3 socket") will be similarly retried after backoffs.
-accesskeyid idstring
-secretaccesskey idstring: Each defaults to an empty string. -These must be set before any calls are made. This is your S3 ID. -Once you sign up for an account, go to http://www.amazonaws.com/, -sign in, go to the "Your Web Services Account" button, pick "AWS -Access Identifiers", and your access key ID and secret access keys -will be available. All S3::REST calls are authenticated. -Blame Amazon for the poor choice of names.
-service-access-point FQDN: Defaults to "s3.amazonaws.com". This is the fully-qualified domain -name of the server to contact for S3::REST calls. You should -probably never need to touch this, unless someone else implements -a compatible service, or you wish to test something by pointing -the library at your own service.
-slop-seconds integer: When comparing dates between Amazon and the local machine, -two dates within this many seconds of each other are considered -the same. Useful for clock drift correction, processing overhead -time, and so on.
-use-tls boolean: Defaults to false. This is not yet implemented. If true, S3::REST will -negotiate a TLS connection to Amazon. If false, unencrypted connections -are used.
-bucket-prefix string: Defaults to "TclS3". This string is used by S3::SuggestBucketName -if that command is passed an empty string as an argument. It is used -to distinguish different applications using the Amazon service. -Your application should always set this to keep from interfering with -the buckets of other users of Amazon S3 or with other buckets of the -same user.
-default-compare always|never|exists|missing|newer|date|checksum|different: Defaults to "always." If no -compare is specified on -S3::Put, S3::Get, or S3::Delete, this comparison is used. -See those commands for a description of the meaning.
-default-separator string: Defaults to "/". This is currently unused. It might make sense to use -this for S3::Push and S3::Pull, but allowing resources to -have slashes in their names that aren't marking directories would be -problematic. Hence, this currently does nothing.
-default-acl private|public-read|public-read-write|authenticated-read|keep|calc: Defaults to an empty string. If no -acl argument is provided to S3::Put or -S3::Push, this string is used -(given as the x-amz-acl header if not keep or calc). If this is also -empty, no x-amz-acl header is generated. -This is not used by S3::REST.
-default-bucket bucketname: If no bucket is given to S3::GetBucket, S3::PutBucket, -S3::Get, S3::Put, -S3::Head, S3::Acl, -S3::Delete, S3::Push, -S3::Pull, or S3::Toss, and if this configuration variable -is not an empty string (and not simply "/"), then this value -will be used for the bucket. This is useful if one program does -a large amount of resource manipulation within a single bucket.

S3::SuggestBucket ?name?

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

S3::REST dict

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

The possible input keys are these:

verb GET|PUT|DELETE|HEAD: This required item indicates the verb to be used.
resource string: This required item indicates the resource to be accessed. -A leading / is added if not there already. It will -be URL-encoded for you if necessary. Do not supply a -resource name that is already URL-encoded.
?rtype torrent|acl?: This indicates a torrent or acl resource is being manipulated. -Do not include this in the resource key, or the -"?" separator will get URL-encoded.
?parameters dict?: This optional dictionary provides parameters added to the URL -for the transaction. The keys must be in the correct case -(which is confusing in the Amazon documentation) and the -values must be valid. This can be an empty dictionary or -omitted entirely if no parameters are desired. No other -error checking on parameters is performed.
?headers dict?: This optional dictionary provides headers to be added -to the HTTP request. The keys must be in lower case -for the authentication to work. The values must not contain -embedded newlines or carriage returns. This is primarily -useful for adding x-amz-* headers. Since authentication -is calculated by S3::REST, do not add that header here. -Since content-type gets its own key, also do not add -that header here.
?inbody contentstring?: This optional item, if provided, gives the content that will -be sent. It is sent with a tranfer encoding of binary, and -only the low bytes are used, so use [encoding convertto utf-8] -if the string is a utf-8 string. This is written all in one blast, -so if you are using non-blocking mode and the inbody is -especially large, you may wind up blocking on the write socket.
?infile filename?: This optional item, if provided, and if inbody is not provided, -names the file from which the body of the HTTP message will be -constructed. The file is opened for reading and sent progressively -by [fcopy], so it should not block in non-blocking mode -even if the file is very large. The file is transfered in -binary mode, so the bytes on your disk will match the bytes -in your resource. Due to HTTP restrictions, it must be possible to -use [file size] on this file to determine the size at the -start of the transaction.
?S3chan channel?: This optional item, if provided, indicates the already-open socket -over which the transaction should be conducted. If not provided, -a connection is made to the service access point specified via -S3::Configure, which is normally s3.amazonaws.com. If this -is provided, the channel is not closed at the end of the transaction.
?outchan channel?: This optional item, if provided, indicates the already-open channel -to which the body returned from S3 should be written. That is, -to retrieve a large resource, open a file, set the translation mode, -and pass the channel as the value of the key outchan. Output -will be written to the channel in pieces so memory does not fill -up unnecessarily. The channel is not closed at the end of the transaction.
?resultvar varname?: This optional item, if provided, indicates that S3::REST should -run in non-blocking mode. The varname should be fully qualified -with respect to namespaces and cannot be local to a proc. If provided, -the result of the S3::REST call is assigned to this variable once -everything has completed; use trace or vwait to know when this has happened. -If this key is not provided, the result is simply returned from the -call to S3::REST and no calls to the eventloop are invoked from -within this call.
?throwsocket throw|return?: This optional item, if provided, indicates that S3::REST should -throw an error if throwmode is throw and a socket error is encountered. -It indicates that S3::REST should return the error code in the -returned dictionary if a socket error is encountered and this is -set to return. If throwsocket is set to return or -if the call is not blocking, then a socket error (i.e., an error -whose error code starts with "S3 socket" will be returned in the -dictionary as error, errorInfo, and errorCode. -If a foreground call is made (i.e., resultvar is not provided), -and this option is not provided or is set to throw, then -error will be invoked instead.

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

error errorstring
errorInfo errorstring
errorCode errorstring: If an error is caught, these three keys will be set in the result. -Note that S3::REST does not consider a non-2XX HTTP -return code as an error. The errorCode value will be -formatted according to the ERROR REPORTING description. -If these are present, other keys described here might not be.
httpstatus threedigits: The three-digit code from the HTTP transaction. 2XX for good, -5XX for server error, etc.
httpmessage text: The textual result after the status code. "OK" or "Forbidden" -or etc.
outbody contentstring: If outchan was not specified, this key will hold a -reference to the (unencoded) contents of the body returned. -If Amazon returned an error (a la the httpstatus not a 2XX value), -the error message will be in outbody or written to -outchan as appropriate.
outheaders dict: This contains a dictionary of headers returned by Amazon. -The keys are always lower case. It's mainly useful for -finding the x-amz-meta-* headers, if any, although things -like last-modified and content-type are also useful. -The keys of this dictionary are always lower case. -Both keys and values are trimmed of extraneous whitespace.

HIGH LEVEL COMMANDS

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

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

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

-blocking boolean

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

-parse-xml xmlstring

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

-bucket bucketname

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

-resource resourcename

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

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

always: Always copy the data. This is the default.
never: Never copy the data. This is essentially a no-op, except in S3::Push and S3::Pull where the -delete flag might make a difference.
exists: Copy the data only if the destination already exists.
missing: Copy the data only if the destination does not already exist.
newer: Copy the data if the destination is missing, or if the date on the source is -newer than the date on the destination by at -least S3::Configure -slop-seconds seconds. If the source is -Amazon, the date is taken from the Last-Modified header. If the -source is local, it is taken as the mtime of the file. If the source data -is specified in a string rather than a file, it is taken as right now, -via [clock seconds].
date: Like newer, except copy if the date is newer or older.
checksum: Calculate the MD5 checksum on the local file or string, ask Amazon for the eTag -of the resource, and copy the data if they're different. Copy the data -also if the destination is missing. Note that this can be slow with -large local files unless the C version of the MD5 support is available.
different: Copy the data if the destination does not exist. -If the destination exists and an actual file name was specified -(rather than a content string), -and the date on the file differs from the date on the resource, -copy the data. -If the data is provided as a content string, the "date" is treated -as "right now", so it will likely always differ unless slop-seconds is large. -If the dates are the same, the MD5 checksums are compared, and the -data is copied if the checksums differ.

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

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

-blocking boolean

See above for standard definition.

-parse-xml xmlstring

See above for standard definition.

-result-type REST

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

-result-type xml

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

-result-type pxml

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

-result-type dict

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

Owner/ID: The Amazon AWS ID (in hex) of the owner of the bucket.
Owner/DisplayName: The Amazon AWS ID's Display Name.
Bucket/Name: A list of names, one for each bucket.
Bucket/CreationDate: A list of dates, one for each bucket, -in the same order as Bucket/Name, in ISO format (as returned by Amazon).

-result-type names

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

-result-type owner

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

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

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

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

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

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

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

-bucket bucketname

The standard bucket argument.

-blocking boolean

The standard blocking argument.

-parse-xml xmlstring

The standard parse-xml argument.

-max-count integer

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

-prefix prefixstring

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

-delimiter delimiterstring

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

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

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

REST

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

xml

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

pxml

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

names

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

dict

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

Name: The name of the bucket (from the final call to S3::REST).
Prefix: From the final call to S3::REST.
Marker: From the final call to S3::REST.
MaxKeys: From the final call to S3::REST.
IsTruncated: From the final call to S3::REST, so -always false if -max-count is not specified.
NextMarker: Always provided if IsTruncated is true, and -calculated of Amazon does not provide it. May be empty if IsTruncated is false.
Key: A list of names of resources in the bucket matching the -prefix and -delimiter restrictions.
LastModified: A list of times of resources in the bucket, in the same -order as Key, in the format returned by Amazon. (I.e., it is not parsed into -a seconds-from-epoch.)
ETag: A list of entity tags (a.k.a. MD5 checksums) in the same order as Key.
Size: A list of sizes in bytes of the resources, in the same order as Key.
Owner/ID: A list of owners of the resources in the bucket, in the same order as Key.
Owner/DisplayName: A list of owners of the resources in the bucket, in the same order as Key. These are the display names.
CommonPrefixes/Prefix: A list of prefixes common to multiple entities. This is present only if -delimiter was supplied.

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

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

-bucket: This specifies the bucket into which the resource will be written. -Leading and/or trailing slashes are removed for you, as are spaces.
-resource: This is the full name of the resource within the bucket. A single -leading slash is removed, but not a trailing slash. -Spaces are not trimmed.
-blocking: The standard blocking flag.
-file: If this is specified, the filename must exist, must be readable, -and must not be a special or directory file. [file size] must -apply to it and must not change for the lifetime of the call. The -default content-type is calculated based on the name and/or contents -of the file. Specifying this is an error if -content is -also specified, but at least one of -file or -content must -be specified. (The file is allowed to not exist or not be readable if --compare never is specified.)
-content: If this is specified, the contentstring is sent as the body -of the resource. The content-type defaults to "application/octet-string". -Only the low bytes are sent, so non-ASCII should use the appropriate encoding -(such as [encoding convertto utf-8]) before passing it -to this routine, if necessary. Specifying this is an error if -file -is also specified, but at least one of -file or -content must -be specified.
-acl: This defaults to S3::Configure -default-acl if not specified. -It sets the x-amz-acl header on the PUT operation. -If the value provided is calc, the x-amz-acl header is -calculated based on the I/O permissions of the file to be uploaded; -it is an error to specify calc and -content. -If the value provided is keep, the acl of the resource -is read before the PUT (or the default is used if the -resource does not exist), then set back to what it -was after the PUT (if it existed). An error will occur if -the resource is successfully written but the kept ACL cannot -be then applied. This should never happen. -Note: calc is not currently fully implemented.
-x-amz-meta-*: If any header starts with "-x-amz-meta-", its contents are added to the -PUT command to be stored as metadata with the resource. Again, no -encoding is performed, and the metadata should not contain characters -like newlines, carriage returns, and so on. It is best to stick with -simple ASCII strings, or to fix the library in several places.
-content-type: This overrides the content-type calculated by -file or -sets the content-type for -content.
-compare: This is the standard compare mode argument. S3::Put returns -1 if the data was copied or 0 if the data was skipped due to -the comparison mode so indicating it should be skipped.

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

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

-bucket: This specifies the bucket from which the resource will be read. -Leading and/or trailing slashes are removed for you, as are spaces.
-resource: This is the full name of the resource within the bucket. A single -leading slash is removed, but not a trailing slash. -Spaces are not trimmed.
-blocking: The standard blocking flag.
-file: If this is specified, the body of the resource will be read into this file, -incrementally without pulling it entirely into memory first. The parent -directory must already exist. If the file already exists, it must be -writable. If an error is thrown part-way through the process and the -file already existed, it may be clobbered. If an error is thrown part-way -through the process and the file did not already exist, any partial -bits will be deleted. Specifying this is an error if -content -is also specified, but at least one of -file or -content must -be specified.
-timestamp: This is only valid in conjunction with -file. It may be specified -as now or aws. The default is now. If now, the file's -modification date is left up to the system. If aws, the file's -mtime is set to match the Last-Modified header on the resource, synchronizing -the two appropriately for -compare date or --compare newer.
-content: If this is specified, the contentvarname is a variable in the caller's -scope (not necessarily global) that receives the value of the body of -the resource. No encoding is done, so if the resource (for example) represents -a UTF-8 byte sequence, use [encoding convertfrom utf-8] to get a valid -UTF-8 string. If this is specified, the -compare is ignored unless -it is never, in which case no assignment to contentvarname is -performed. Specifying this is an error if -file is also specified, -but at least one of -file or -content must be specified.
-compare: This is the standard compare mode argument. S3::Get returns -1 if the data was copied or 0 if the data was skipped due to -the comparison mode so indicating it should be skipped.
-headers: If this is specified, the headers resulting from the fetch are stored -in the provided variable, as a dictionary. This will include content-type -and x-amz-meta-* headers, as well as the usual HTTP headers, the x-amz-id -debugging headers, and so on. If no file is fetched (due to -compare -or other errors), no assignment to this variable is performed.

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

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

-bucket: This specifies the bucket from which the resource will be read. -Leading and/or trailing slashes are removed for you, as are spaces.
-resource: This is the full name of the resource within the bucket. A single -leading slash is removed, but not a trailing slash. -Spaces are not trimmed.
-blocking: The standard blocking flag.
-dict: If specified, the resulting dictionary from the S3::REST -call is assigned to the indicated (not necessarily global) variable -in the caller's scope.
-headers: If specified, the dictionary of headers from the result are assigned -to the indicated (not necessarily global) variable in the caller's scope.
-status: If specified, the indicated (not necessarily global) variable in -the caller's scope is assigned a 2-element list. The first element is -the 3-digit HTTP status code, while the second element is -the HTTP message (such as "OK" or "Forbidden").

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

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

-blocking boolean

See above for standard definition.

-bucket

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

-resource

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

-parse-xml xml

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

-result-type REST

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

-result-type xml

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

-result-type pxml

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

-result-type dict

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

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

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

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

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

-blocking boolean

See above for standard definition.

-bucket

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

-resource

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

-owner

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

-acl

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

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

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

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

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

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

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

-bucket: This specifies the bucket from which the resource will be deleted. -Leading and/or trailing slashes are removed for you, as are spaces.
-resource: This is the full name of the resource within the bucket. A single -leading slash is removed, but not a trailing slash. -Spaces are not trimmed.
-blocking: The standard blocking flag.
-status: If specified, the indicated (not necessarily global) variable -in the caller's scope is set to a two-element list. The first -element is the 3-digit HTTP status code. The second element -is the HTTP message (such as "OK" or "Forbidden"). Note that -Amazon's DELETE result is 204 on success, that being the -code indicating no content in the returned body.

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

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

-bucket

This names the bucket into which data will be pushed.

-directory

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

-prefix

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

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

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

-blocking

This is the standard blocking option.

-compare

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

-x-amz-meta-*

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

-acl

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

-delete

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

-error

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

throw: The error is rethrown with the same errorCode.
break: Processing stops without throwing an error, the error is recorded -in the return value, and the command returns with a normal return. -The calls to S3::Delete are not started.
continue: This is the default. Processing continues without throwing, -recording the error in the return result, and resuming with the -next file in the local directory to be copied.

-progress

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

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

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

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

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

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

-bucket: This names the bucket from which data will be pulled.
-directory: This names the local directory into which files will be written -It must exist, be readable via [glob], writable for file creation, -and so on. If only some of the files therein are writable, -S3::Pull will GET -those files that are writable and return in its results the list -of files that could not be opened.
-prefix: The prefix of resources that will be considered for retrieval. -See S3::Push for more details, examples, etc. (Of course, -S3::Pull reads rather than writes, but the prefix is -treated similarly.)
-blocking: This is the standard blocking option.
-compare: This is passed to each invocation of S3::Get if provided. -Naturally, S3::Configure -default-compare is -used if this is not provided.
-timestamp: This is passed to each invocation of S3::Get if provided.
-delete: If this is specified and true, files that exist in the -directory -that are not in the -prefix will be deleted after all resources -have been copied. In addition, empty directories (other than the -top-level -directory) will be deleted, as -Amazon S3 has no concept of an empty directory.
-error: See S3::Push for a description of this option.
-progress: See S3::Push for a description of this option. -It differs slightly in that local directories may be included -with a trailing slash to indicate they are directories.

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

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

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

-bucket: The bucket from which resources will be deleted.
-blocking: The standard blocking option.
-prefix: The prefix for resources to be deleted. Any resource that -starts with this string will be deleted. This is required. -To delete everything in the bucket, pass an empty string -for the prefix.
-error: If this is "throw", S3::Toss rethrows any errors -it encounters. If this is "break", S3::Toss returns -with a normal return after the first error, recording that -error in the return result. If this is "continue", which is -the default, S3::Toss continues on and lists all -errors in the return result.
-progress: If this is specified and not an empty string, the script -prefix will be invoked several times in the context of the caller -with additional arguments appended. Initially, it will be invoked -with the first additional argument being args and the second -being the processed list of arguments to S3::Toss. Then it -is invoked with remote as the first additional argument and -the list of suffixes in the bucket to be deleted as the second -additional argument. Then it is invoked with the first additional -argument being delete and the second additional argument being -the suffix deleted and the third additional argument being "deleted" -or "notdeleted" depending on whether S3::Delete threw an error. -Finally, the script prefix is invoked with a first additional argument -of "finished" and a second additional argument of the return value.

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

LIMITATIONS

The pure-Tcl MD5 checking is slow. If you are processing -files in the megabyte range, consider ensuring binary support is available.
The commands S3::Pull and S3::Push fetch a -directory listing which includes timestamps and MD5 hashes, -then invoke S3::Get and S3::Put. If -a complex -compare mode is specified, S3::Get and -S3::Put will invoke a HEAD operation for each file to fetch -timestamps and MD5 hashes of each resource again. It is expected that -a future release of this package will solve this without any API changes.
The commands S3::Pull and S3::Push fetch a -directory listing without using -max-count. The entire -directory is pulled into memory at once. For very large buckets, -this could be a performance problem. The author, at this time, -does not plan to change this behavior. Welcome to Open Source.
S3::Sync is neither designed nor implemented yet. -The intention would be to keep changes synchronised, so changes -could be made to both the bucket and the local directory and -be merged by S3::Sync.
Nor is --compare calc fully implemented. This is primarily due to -Windows not providing a convenient method for distinguishing between -local files that are "public-read" or "public-read-write". Assistance -figuring out TWAPI for this would be appreciated. The U**X semantics -are difficult to map directly as well. See the source for details. -Note that there are not tests for calc, since it isn't done yet.
The HTTP processing is implemented within the library, -rather than using a "real" HTTP package. Hence, multi-line headers -are not (yet) handled correctly. Do not include carriage returns or -linefeeds in x-amz-meta-* headers, content-type values, and so on. -The author does not at this time expect to improve this.
Internally, S3::Push and S3::Pull and S3::Toss -are all very similar and should be refactored.
The idea of using -compare never --delete true to delete files that have been -deleted from one place but not the other yet not copying -changed files is untested.

USAGE SUGGESTIONS

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

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

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

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

FUTURE DEVELOPMENTS

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

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

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

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

TLS Security Considerations

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

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

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

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

Bugs, Ideas, Feedback

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

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

Keywords

amazon, cloud, s3

Category

Networking

Copyright

DELETED embedded/www/tcllib/files/modules/amazon-s3/xsxp.html Index: embedded/www/tcllib/files/modules/amazon-s3/xsxp.html ================================================================== --- embedded/www/tcllib/files/modules/amazon-s3/xsxp.html +++ /dev/null @@ -1,244 +0,0 @@ -

- -

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

Name

xsxp - eXtremely Simple Xml Parser

Table Of Contents
Synopsis
Description
COMMANDS
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require xsxp 1
package require xml

xsxp::parse xml
xsxp::fetch pxml path ?part?
xsxp::fetchall pxml_list path ?part?
xsxp::only pxml tagname
xsxp::prettyprint pxml ?chan?

Description

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

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

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

COMMANDS

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

xsxp::parse xml

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

The first element is the name of the tag.
The second element is an array-get formatted list of key/value pairs. The keys are attribute names and the values are attribute values. This is an empty list if there are no attributes on the tag.
The third through end elements are the children of the node, if any. Each child is, recursively, a pxml.
Note that if the zero'th element, i.e. the tag name, is "%PCDATA", then -the attributes will be empty and the third element will be the text of the element. In addition, if an element's contents consists only of PCDATA, it will have only one child, and all the PCDATA will be concatenated. In other words, -this parser works poorly for XML with elements that contain both child tags and PCDATA. Since Amazon S3 does not do this (and for that matter most -uses of XML where XML is a poor choice don't do this), this is probably -not a serious limitation.

xsxp::fetch pxml path ?part?

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

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

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

%ALL: returns the entire selected element.
%TAGNAME: returns lindex 0 of the selected element.
%ATTRIBUTES: returns index 1 of the selected element.
%CHILDREN: returns lrange 2 through end of the selected element, -resulting in a list of elements being returned.
%PCDATA: returns a concatenation of all the bodies of -direct children of this node whose tag is %PCDATA. -It throws an error if no such children are found. That -is, part=%PCDATA means return the textual content found -in that node but not its children nodes.
%PCDATA?: is like %PCDATA, but returns an empty string if -no PCDATA is found.

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

xsxp::fetch $pxml {body p#4 b} %PCDATA

xsxp::fetchall pxml_list path ?part?

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

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

xsxp::only pxml tagname

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

xsxp::prettyprint pxml ?chan?

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

Bugs, Ideas, Feedback

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

Keywords

dom, parser, xml

Category

Text processing

Copyright

DELETED embedded/www/tcllib/files/modules/asn/asn.html Index: embedded/www/tcllib/files/modules/asn/asn.html ================================================================== --- embedded/www/tcllib/files/modules/asn/asn.html +++ /dev/null @@ -1,504 +0,0 @@ - -

- -

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

Name

asn - ASN.1 BER encoder/decoder

Table Of Contents
Synopsis
Description
PUBLIC API -
- ENCODER
- DECODER
- HANDLING TAGS
-
EXAMPLES
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require asn ?0.8.4?

::asn::asnSequence evalue...
::asn::asnSequenceFromList elist
::asn::asnSet evalue...
::asn::asnSetFromList elist
::asn::asnApplicationConstr appNumber evalue...
::asn::asnApplication appNumber data
::asn::asnChoice appNumber evalue...
::asn::asnChoiceConstr appNumber evalue...
::asn::asnInteger number
::asn::asnEnumeration number
::asn::asnBoolean bool
::asn::asnContext context data
::asn::asnContextConstr context evalue...
::asn::asnObjectIdentifier idlist
::asn::asnUTCTime utcstring
::asn::asnNull
::asn::asnBitString string
::asn::asnOctetString string
::asn::asnNumericString string
::asn::asnPrintableString string
::asn::asnIA5String string
::asn::asnBMPString string
::asn::asnUTF8String string
::asn::asnString string
::asn::defaultStringType ?type?
::asn::asnPeekByte data_var byte_var
::asn::asnGetLength data_var length_var
::asn::asnGetResponse chan data_var
::asn::asnGetInteger data_var int_var
::asn::asnGetEnumeration data_var enum_var
::asn::asnGetOctetString data_var string_var
::asn::asnGetString data_var string_var ?type_var?
::asn::asnGetNumericString data_var string_var
::asn::asnGetPrintableString data_var string_var
::asn::asnGetIA5String data_var string_var
::asn::asnGetBMPString data_var string_var
::asn::asnGetUTF8String data_var string_var
::asn::asnGetUTCTime data_var utc_var
::asn::asnGetBitString data_var bits_var
::asn::asnGetObjectIdentifier data_var oid_var
::asn::asnGetBoolean data_var bool_var
::asn::asnGetNull data_var
::asn::asnGetSequence data_var sequence_var
::asn::asnGetSet data_var set_var
::asn::asnGetApplication data_var appNumber_var ?content_var? ?encodingType_var?
::asn::asnGetContext data_var contextNumber_var ?content_var? ?encodingType_var?
::asn::asnPeekTag data_var tag_var tagtype_var constr_var
::asn::asnTag tagnumber ?class? ?tagstyle?
::asn::asnRetag data_var newTag

Description

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

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

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

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

PUBLIC API

ENCODER

::asn::asnSequence evalue...: Takes zero or more encoded values, packs them into an ASN sequence and -returns its encoded binary form.
::asn::asnSequenceFromList elist: Takes a list of encoded values, packs them into an ASN sequence and -returns its encoded binary form.
::asn::asnSet evalue...: Takes zero or more encoded values, packs them into an ASN set and -returns its encoded binary form.
::asn::asnSetFromList elist: Takes a list of encoded values, packs them into an ASN set and -returns its encoded binary form.
::asn::asnApplicationConstr appNumber evalue...: Takes zero or more encoded values, packs them into an ASN application -construct and returns its encoded binary form.
::asn::asnApplication appNumber data: Takes a single encoded value data, packs it into an ASN -application construct and returns its encoded binary form.
::asn::asnChoice appNumber evalue...: Takes zero or more encoded values, packs them into an ASN choice -construct and returns its encoded binary form.
::asn::asnChoiceConstr appNumber evalue...: Takes zero or more encoded values, packs them into an ASN choice -construct and returns its encoded binary form.
::asn::asnInteger number: Returns the encoded form of the specified integer -number.
::asn::asnEnumeration number: Returns the encoded form of the specified enumeration id -number.
::asn::asnBoolean bool: Returns the encoded form of the specified boolean value -bool.
::asn::asnContext context data: Takes an encoded value and packs it into a constructed value with -application tag, the context number.
::asn::asnContextConstr context evalue...: Takes zero or more encoded values and packs them into a constructed -value with application tag, the context number.
::asn::asnObjectIdentifier idlist: Takes a list of at least 2 integers describing an object identifier -(OID) value, and returns the encoded value.
::asn::asnUTCTime utcstring: Returns the encoded form of the specified UTC time string.
::asn::asnNull: Returns the NULL encoding.
::asn::asnBitString string: Returns the encoded form of the specified string.
::asn::asnOctetString string: Returns the encoded form of the specified string.
::asn::asnNumericString string: Returns the string encoded as ASN.1 NumericString. Raises an -error if the string contains characters other than decimal -numbers and space.
::asn::asnPrintableString string: Returns the string encoding as ASN.1 PrintableString. Raises an -error if the string contains characters which are not allowed by -the Printable String datatype. The allowed characters are A-Z, a-z, -0-9, space, apostrophe, colon, parentheses, plus, minus, comma, -period, forward slash, question mark, and the equals sign.
::asn::asnIA5String string: Returns the string encoded as ASN.1 IA5String. Raises an error -if the string contains any characters outside of the US-ASCII -range.
::asn::asnBMPString string: Returns the string encoded as ASN.1 Basic Multilingual Plane -string (Which is essentialy big-endian UCS2).
::asn::asnUTF8String string: Returns the string encoded as UTF8 String. Note that some legacy -applications such as Windows CryptoAPI do not like UTF8 strings. Use -BMPStrings if you are not sure.
::asn::asnString string: Returns an encoded form of string, choosing the most restricted -ASN.1 string type possible. If the string contains non-ASCII -characters, then there is more than one string type which can be -used. See ::asn::defaultStringType.
::asn::defaultStringType ?type?: Selects the string type to use for the encoding of non-ASCII -strings. Returns current default when called without argument. If the -argument type is supplied, it should be either UTF8 or -BMP to choose UTF8String or BMPString respectively.

DECODER

General notes:

Nearly all decoder commands take two arguments. These arguments are variable -names, except for ::asn::asnGetResponse. The first variable -contains the encoded ASN value to decode at the beginning, and more, -and the second variable is where the value is stored to. The remainder -of the input after the decoded value is stored back into the -datavariable.
After extraction the data variable is always modified first, before by -writing the extracted value to its variable. This means that if both -arguments refer to the same variable, it will always contain the -extracted value after the call, and not the remainder of the input.

::asn::asnPeekByte data_var byte_var

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

::asn::asnGetLength data_var length_var

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

::asn::asnGetResponse chan data_var

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

::asn::asnGetInteger data_var int_var

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

::asn::asnGetEnumeration data_var enum_var

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

::asn::asnGetOctetString data_var string_var

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

::asn::asnGetString data_var string_var ?type_var?

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

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

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

::asn::asnGetNumericString data_var string_var

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

::asn::asnGetPrintableString data_var string_var

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

::asn::asnGetIA5String data_var string_var

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

::asn::asnGetBMPString data_var string_var

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

::asn::asnGetUTF8String data_var string_var

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

::asn::asnGetUTCTime data_var utc_var

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

::asn::asnGetBitString data_var bits_var

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

::asn::asnGetObjectIdentifier data_var oid_var

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

::asn::asnGetBoolean data_var bool_var

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

::asn::asnGetNull data_var

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

::asn::asnGetSequence data_var sequence_var

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

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

::asn::asnGetSet data_var set_var

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

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

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

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

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

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

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

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

HANDLING TAGS

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

::asn::asnPeekTag data_var tag_var tagtype_var constr_var: The ::asn::asnPeekTag command can be used to take a peek at the data and decode the tag value, without -removing it from the data. The tag_var gets set to the tag number, while the tagtype_var gets set -to the class of the tag. (Either UNIVERSAL, CONTEXT, APPLICATION or PRIVATE). The constr_var is set to 1 if the -tag is for a constructed value, and to 0 for not constructed. It returns the length of the tag.
::asn::asnTag tagnumber ?class? ?tagstyle?: The ::asn::asnTag can be used to create a tag value. The tagnumber gives the number of the tag, while -the class gives one of the classes (UNIVERSAL,CONTEXT,APPLICATION or PRIVATE). The class may be abbreviated to just the first letter (U,C,A,P), -default is UNIVERSAL. -The tagstyle is either C for Constructed encoding, or P for primitve encoding. It defaults to P. You can also use 1 instead of C and -0 instead of P for direct use of the values returned by ::asn::asnPeekTag.
::asn::asnRetag data_var newTag: Replaces the tag in front of the data in data_var with newTag. The new Tag can be created using the ::asn::asnTag command.

EXAMPLES

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

Bugs, Ideas, Feedback

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

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

Keywords

asn, ber, cer, der, internet, protocol, x.208, x.209

Category

Networking

Copyright

DELETED embedded/www/tcllib/files/modules/base32/base32.html Index: embedded/www/tcllib/files/modules/base32/base32.html ================================================================== --- embedded/www/tcllib/files/modules/base32/base32.html +++ /dev/null @@ -1,200 +0,0 @@ - -

- -

base32(n) 0.1 tcllib "Base32 encoding"

Name

base32 - base32 standard encoding

Table Of Contents
Synopsis
Description
API
Code map
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

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

::base32::encode string
::base32::decode estring

Description

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

API

::base32::encode string

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

::base32::decode estring

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

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

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

the input contains characters which are not valid output of a base32 encoder,
the length of the input is not a multiple of eight,
padding appears not at the end of input, but in the middle,
the padding has not of length six, four, three, or one characters,

Code map

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

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

Bugs, Ideas, Feedback

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

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

Keywords

base32, rfc3548

Category

Text processing

Copyright

Public domain

DELETED embedded/www/tcllib/files/modules/base32/base32core.html Index: embedded/www/tcllib/files/modules/base32/base32core.html ================================================================== --- embedded/www/tcllib/files/modules/base32/base32core.html +++ /dev/null @@ -1,190 +0,0 @@ - -

- -

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

Name

base32::core - Expanding basic base32 maps

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

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

::base32::core::define map forwvar backwvar ivar
::base32::core::valid string pattern mvar

Description

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

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

API

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

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

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

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

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

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

The length of the input is not a multiple of eight,
The padding appears not at the end of input, but in the middle,
The padding has not of length six, four, three, or one characters,

Bugs, Ideas, Feedback

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

Keywords

base32

Category

Text processing

Copyright

Public domain

DELETED embedded/www/tcllib/files/modules/base32/base32hex.html Index: embedded/www/tcllib/files/modules/base32/base32hex.html ================================================================== --- embedded/www/tcllib/files/modules/base32/base32hex.html +++ /dev/null @@ -1,202 +0,0 @@ - -

- -

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

Name

base32::hex - base32 extended hex encoding

Table Of Contents
Synopsis
Description
API
Code map
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

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

::base32::hex::encode string
::base32::hex::decode estring

Description

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

API

::base32::hex::encode string

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

::base32::hex::decode estring

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

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

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

the input contains characters which are not valid output - of a extended hex base32 encoder,
the length of the input is not a multiple of eight,
padding appears not at the end of input, but in the middle,
the padding has not of length six, four, three, or one characters,

Code map

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

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

Bugs, Ideas, Feedback

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

Keywords

base32, hex, rfc3548

Category

Text processing

Copyright

Public domain

DELETED embedded/www/tcllib/files/modules/base64/ascii85.html Index: embedded/www/tcllib/files/modules/base64/ascii85.html ================================================================== --- embedded/www/tcllib/files/modules/base64/ascii85.html +++ /dev/null @@ -1,198 +0,0 @@ -

- -

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

Name

ascii85 - ascii85-encode/decode binary data

Table Of Contents
Synopsis
Description
EXAMPLES
References
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require ascii85 ?1.0?

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

Description

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

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

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

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

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

::ascii85::decode string

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

EXAMPLES

-% ascii85::encode "Hello, world"
-87cURD_*#TDfTZ)
-

-% ascii85::encode [string repeat xyz 24]
-G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G
-^4U[H$X^\H?a^]
-% ascii85::encode -wrapchar "" [string repeat xyz 24]
-G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]
-

-# NOTE: ascii85 encodes BINARY strings.
-% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
-% set encoded [ascii85::encode $chemical]
-6fN]R8E,5Pidu\UiduhZidua
-% set caffeine [encoding convertfrom utf-8 [ascii85::decode $encoded]]
-

References

http://en.wikipedia.org/wiki/Ascii85
Postscript Language Reference Manual, 3rd Edition, page 131. - http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf

Bugs, Ideas, Feedback

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

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

Keywords

ascii85, encoding

Category

Text processing

Copyright

DELETED embedded/www/tcllib/files/modules/base64/base64.html Index: embedded/www/tcllib/files/modules/base64/base64.html ================================================================== --- embedded/www/tcllib/files/modules/base64/base64.html +++ /dev/null @@ -1,192 +0,0 @@ -

- -

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

Name

base64 - base64-encode/decode binary data

Table Of Contents
Synopsis
Description
EXAMPLES
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8
package require base64 ?2.4.2?

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

Description

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

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

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

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

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

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

::base64::decode string

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

EXAMPLES

-% base64::encode "Hello, world"
-SGVsbG8sIHdvcmxk
-

-% base64::encode [string repeat xyz 20]
-eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
-eHl6eHl6eHl6
-% base64::encode -wrapchar "" [string repeat xyz 20]
-eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
-

-# NOTE: base64 encodes BINARY strings.
-% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
-% set encoded [base64::encode $chemical]
-Q+KCiEjigoHigoBO4oKET+KCgg==
-% set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]]
-

Bugs, Ideas, Feedback

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

Keywords

base64, encoding

Category

Text processing

Copyright

DELETED embedded/www/tcllib/files/modules/base64/uuencode.html Index: embedded/www/tcllib/files/modules/base64/uuencode.html ================================================================== --- embedded/www/tcllib/files/modules/base64/uuencode.html +++ /dev/null @@ -1,214 +0,0 @@ -

- -

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

Name

uuencode - UU-encode/decode binary data

Table Of Contents
Synopsis
Description
OPTIONS
EXAMPLES
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8
package require uuencode ?1.1.4?

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

Description

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

::uuencode::encode string: returns the uuencoded data. This will encode all the data passed in -even if this is longer than the uuencode maximum line length. If the -number of input bytes is not a multiple of 3 then additional 0 bytes -are added to pad the string.
::uuencode::decode string: Decodes the given encoded data. This will return any padding -characters as well and it is the callers responsibility to deal with -handling the actual length of the encoded data. (see uuencode).
::uuencode::uuencode ?-name string? ?-mode octal? (-file filename | ?--? string)
::uuencode::uudecode (-file filename | ?--? string): UUDecode a file or block of data. A file may contain more than one -embedded file so the result is a list where each element is a three -element list of filename, mode value and data.

OPTIONS

-filename name: Cause the uuencode or uudecode commands to read their data from the -named file rather that taking a string parameter.
-name string: The uuencoded data header line contains the suggested file name to be -used when unpacking the data. Use this option to change this from the -default of "data.dat".
-mode octal: The uuencoded data header line contains a suggested permissions bit -pattern expressed as an octal string. To change the default of 0644 -you can set this option. For instance, 0755 would be suitable for an -executable. See chmod(1).

EXAMPLES

-% set d [uuencode::encode "Hello World!"]
-2&5L;&\\@5V]R;&0A
-

-% uuencode::uudecode $d
-Hello World!
-

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

-% uuencode::uudecode $d
-{hello.txt 644 {Hello World}}
-

Bugs, Ideas, Feedback

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

Keywords

encoding, uuencode

Category

Text processing

Copyright

DELETED embedded/www/tcllib/files/modules/base64/yencode.html Index: embedded/www/tcllib/files/modules/base64/yencode.html ================================================================== --- embedded/www/tcllib/files/modules/base64/yencode.html +++ /dev/null @@ -1,207 +0,0 @@ -

- -

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

Name

yencode - Y-encode/decode binary data

Table Of Contents
Synopsis
Description
OPTIONS
References
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require yencode ?1.1.2?

::yencode::encode string
::yencode::decode string
::yencode::yencode ?-name string? ?-line integer? ?-crc32 boolean? (-file filename | ?--? string)
::yencode::ydecode (-file filename | ?--? string)

Description

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

::yencode::encode string: returns the yEnc encoded data.
::yencode::decode string: Decodes the given yEnc encoded data.
::yencode::yencode ?-name string? ?-line integer? ?-crc32 boolean? (-file filename | ?--? string): Encode a file or block of data.
::yencode::ydecode (-file filename | ?--? string): Decode a file or block of data. A file may contain more than one -embedded file so the result is a list where each element is a three -element list of filename, file size and data.

OPTIONS

-filename name: Cause the yencode or ydecode commands to read their data from the -named file rather that taking a string parameter.
-name string: The encoded data header line contains the suggested file name to be -used when unpacking the data. Use this option to change this from the -default of "data.dat".
-line integer: The yencoded data header line contains records the line length used -during the encoding. Use this option to select a line length other -that the default of 128. Note that NNTP imposes a 1000 character line -length limit and some gateways may have trouble with more than 255 -characters per line.
-crc32 boolean: The yEnc specification recommends the inclusion of a cyclic redundancy -check value in the footer. Use this option to change the default from -true to false.

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

References

http://www.yenc.org/yenc-draft.1.3.txt

Bugs, Ideas, Feedback

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

Keywords

encoding, yEnc, ydecode, yencode

Category

Text processing

Copyright

DELETED embedded/www/tcllib/files/modules/bee/bee.html Index: embedded/www/tcllib/files/modules/bee/bee.html ================================================================== --- embedded/www/tcllib/files/modules/bee/bee.html +++ /dev/null @@ -1,378 +0,0 @@ - -

- -

bee(n) 0.1 tcllib "BitTorrent"

Name

bee - BitTorrent Serialization Format Encoder/Decoder

Table Of Contents
Synopsis
Description
PUBLIC API -
- ENCODER
- DECODER
-
FORMAT DEFINITION
EXAMPLES
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require bee ?0.1?

::bee::encodeString string
::bee::encodeNumber integer
::bee::encodeListArgs value...
::bee::encodeList list
::bee::encodeDictArgs key value...
::bee::encodeDict dict
::bee::decode string ?endvar? ?start?
::bee::decodeIndices string ?endvar? ?start?
::bee::decodeChannel chan -command cmdprefix ?-exact? ?-prefix data?
cmdprefix eof token
cmdprefix error token message
cmdprefix value token value
::bee::decodeCancel token
::bee::decodePush token string

Description

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

PUBLIC API

ENCODER

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

::bee::encodeString string: Returns the bee-encoding of the string.
::bee::encodeNumber integer: Returns the bee-encoding of the integer number.
::bee::encodeListArgs value...: Takes zero or more bee-encoded values and returns the bee-encoding of -their list.
::bee::encodeList list: Takes a list of bee-encoded values and returns the bee-encoding of the -list.
::bee::encodeDictArgs key value...: Takes zero or more pairs of keys and values and returns the -bee-encoding of the dictionary they form. The values are expected to -be already bee-encoded, but the keys must not be. Their encoding will -be done by the command itself.
::bee::encodeDict dict: Takes a dictionary list of string keys and bee-encoded values and -returns the bee-encoding of the list. Note that the keys in the input -must not be bee-encoded already. This will be done by the command -itself.

DECODER

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

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

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

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

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

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

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

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

string

A list containing three elements:

The constant string string, denoting the type of the value.
An integer number greater than or equal to zero. This is the index of -the first character of the bee-value in the input string.
An integer number greater than or equal to zero. This is the index of -the last character of the bee-value in the input string.

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

integer

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

list

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

dictionary

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

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

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

-command

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

cmdprefix eof token: The decoder has reached eof on the channel chan. No further -invocations of the callback will be made after this. The channel has -already been closed at the time of the call, and the token is -not valid anymore as well.
cmdprefix error token message: The decoder encountered an error, which is not eof. For example a -malformed bee-value. The message provides details about the -error. The decoder token is in the same state as for eof, -i.e. invalid. The channel however is kept open.
cmdprefix value token value: The decoder received and successfully decoded a bee-value. -The format of the equivalent tcl value is the same as returned -by ::bee::decode. The channel is still open and the decoder -token is valid. This means that the callback is able to remove the -decoder.

-exact

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

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

-prefix

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

::bee::decodeCancel token

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

::bee::decodePush token string

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

FORMAT DEFINITION

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

String S

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

Integer N

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

List v1 ... vn

A list of the values v1 to vn is encoded by the string -"lBV1...BVne" -where "BVi" is the bee-encoding of the value "vi".

Dict k1 -> v1 ...

A dictionary mapping the string key ki to the value -vi, for i in 1 ... n -is encoded by the string -"dBKiBVi...e" -for i in 1 ... n, where "BKi" is the bee-encoding -of the key string "ki". and "BVi" is the bee-encoding of -the value "vi".

Note: The bee-encoding does not retain the order of the keys in -the input, but stores in a sorted order. The sorting is done for the -"raw strings".

Note that the type of each encoded item can be determined immediately -from the first character of its representation:

i: Integer.
l: List.
d: Dictionary.
[0-9]: String.

By wrapping an integer number into i...e the format -makes sure that they are different from strings, which all begin with -a digit.

EXAMPLES

Bugs, Ideas, Feedback

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

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

Keywords

BitTorrent, bee, bittorrent, serialization, torrent

Category

Networking

Copyright

DELETED embedded/www/tcllib/files/modules/bench/bench.html Index: embedded/www/tcllib/files/modules/bench/bench.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench.html +++ /dev/null @@ -1,335 +0,0 @@ - -

- -

bench(n) 0.4 tcllib "Benchmarking/Performance tools"

Name

bench - bench - Processing benchmark suites

Table Of Contents
Synopsis
Description
PUBLIC API -
- Benchmark execution
- Result manipulation
- Result format
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require bench ?0.4?

::bench::locate pattern paths
::bench::run ?option value...? interp_list file...
::bench::versions interp_list
::bench::del bench_result column
::bench::edit bench_result column newvalue
::bench::merge bench_result...
::bench::norm bench_result column
::bench::out::raw bench_result

Description

This package provides commands for the execution of benchmarks written -in the bench language, and for the processing of results generated by -such execution.

A reader interested in the bench language itself should start with the -bench language introduction and proceed from there to the -formal bench language specification.

PUBLIC API

Benchmark execution

::bench::locate pattern paths

This command locates Tcl interpreters and returns a list containing -their paths. It searches them in the list of paths specified by -the caller, using the glob pattern.

The command resolves soft links to find the actual executables -matching the pattern. Note that only interpreters which are marked as -executable and are actually executable on the current platform are put -into the result.

::bench::run ?option value...? interp_list file...

This command executes the benchmarks declared in the set of files, -once per Tcl interpreter specified via the interp_list, and per -the configuration specified by the options, and then returns the -accumulated timing results. The format of this result is described in -section Result format.

It is assumed that the contents of the files are written in the bench -language.

The available options are

-errors flag

The argument is a boolean value. If set errors in benchmarks are -propagated to the command, aborting benchmark execution. Otherwise -they are recorded in the timing result via a special result code. The -default is to propagate and abort.

-threads n

The argument is a non-negative integer value declaring the number of -threads to use while executing the benchmarks. The default value is -0, to not use threads.

-match pattern

The argument is a glob pattern. Only benchmarks whose description -matches the pattern are executed. The default is the empty string, to -execute all patterns.

-rmatch pattern

The argument is a regular expression pattern. Only benchmarks whose -description matches the pattern are executed. The default is the empty -string, to execute all patterns.

-iters n

The argument is positive integer number, the maximal number of -iterations for any benchmark. The default is 1000. Individual -benchmarks can override this.

-pkgdir path

The argument is a path to an existing, readable directory. Multiple -paths can be specified, simply use the option multiple times, each -time with one of the paths to use.

If no paths were specified the system will behave as before. -If one or more paths are specified, say N, each of the specified -interpreters will be invoked N times, with one of the specified -paths. The chosen path is put into the interpreters' auto_path, -thus allowing it to find specific versions of a package.

In this way the use of -pkgdir allows the user to benchmark -several different versions of a package, against one or more interpreters.

Note: The empty string is allowed as a path and causes the system to -run the specified interpreters with an unmodified auto_path. In case -the package in question is available there as well.

::bench::versions interp_list

This command takes a list of Tcl interpreters, identified by their -path, and returns a dictionary mapping from the interpreters to their -versions. Interpreters which are not actually executable, or fail when -interrogated, are not put into the result. I.e the result may contain -less interpreters than there in the input list.

The command uses builtin command info patchlevel to determine -the version of each interpreter.

Result manipulation

::bench::del bench_result column

This command removes a column, i.e. all benchmark results for a -specific Tcl interpreter, from the specified benchmark result and -returns the modified result.

The benchmark results are in the format described in section -Result format.

The column is identified by an integer number.

::bench::edit bench_result column newvalue

This command renames a column in the specified benchmark result and -returns the modified result. This means that the path of the Tcl -interpreter in the identified column is changed to an arbitrary -string.

The benchmark results are in the format described in section -Result format.

The column is identified by an integer number.

::bench::merge bench_result...

This commands takes one or more benchmark results, merges them into -one big result, and returns that as its result.

All benchmark results are in the format described in section -Result format.

::bench::norm bench_result column

This command normalizes the timing results in the specified benchmark -result and returns the modified result. This means that the cell -values are not times anymore, but factors showing how much faster or -slower the execution was relative to the baseline.

The baseline against which the command normalizes are the timing -results in the chosen column. This means that after the normalization -the values in this column are all 1, as these benchmarks are -neither faster nor slower than the baseline.

A factor less than 1 indicates a benchmark which was faster -than the baseline, whereas a factor greater than 1 indicates a -slower execution.

The benchmark results are in the format described in section -Result format.

The column is identified by an integer number.

::bench::out::raw bench_result

This command formats the specified benchmark result for output to a -file, socket, etc. This specific command does no formatting at all, -it passes the input through unchanged.

For other formatting styles see the packages bench::out::text -and bench::out::csv which provide commands to format -benchmark results for human consumption, or as CSV data importable by -spread sheets, respectively.

Complementary, to read benchmark results from files, sockets etc. look -for the package bench::in and the commands provided by it.

Result format

After the execution of a set of benchmarks the raw result returned by -this package is a Tcl dictionary containing all the relevant -information. -The dictionary is a compact representation, i.e. serialization, of a -2-dimensional table which has Tcl interpreters as columns and -benchmarks as rows. The cells of the table contain the timing -results. -The Tcl interpreters / columns are identified by their paths. -The benchmarks / rows are identified by their description.

The possible keys are all valid Tcl lists of two or three elements and -have one of the following forms:

{interp *}

The set of keys matching this glob pattern capture the information -about all the Tcl interpreters used to run the benchmarks. The second -element of the key is the path to the interpreter.

The associated value is the version of the Tcl interpreter.

{desc *}

The set of keys matching this glob pattern capture the information -about all the benchmarks found in the executed benchmark suite. The -second element of the key is the description of the benchmark, which -has to be unique.

The associated value is irrelevant, and set to the empty string.

{usec * *}

The set of keys matching this glob pattern capture the performance -information, i.e. timing results. The second element of the key is the -description of the benchmark, the third element the path of the Tcl -interpreter which was used to run it.

The associated value is either one of several special result codes, or -the time it took to execute the benchmark, in microseconds. The -possible special result codes are

ERR: Benchmark could not be executed, failed with a Tcl error.
BAD_RES: The benchmark could be executed, however the result from its body did -not match the declared expectations.

Bugs, Ideas, Feedback

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

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

Keywords

benchmark, merging, normalization, performance, testing

Category

Benchmark tools

Copyright

DELETED embedded/www/tcllib/files/modules/bench/bench_intro.html Index: embedded/www/tcllib/files/modules/bench/bench_intro.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench_intro.html +++ /dev/null @@ -1,177 +0,0 @@ - -

- -

bench_intro(n) 1.0 tcllib "Benchmarking/Performance tools"

Name

bench_intro - bench introduction

Table Of Contents
Description
HISTORICAL NOTES
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

The bench (short for benchmark tools), is a set of -related, yet different, entities which are working together for the -easy creation and execution of performance test suites, also known as -benchmarks. These are

A tcl based language for the declaration of test cases. A test case is -represented by a tcl command declaring the various parts needed to -execute it, like setup, cleanup, the commands to test, etc.
A package providing the ability to execute test cases written in that -language.

Which of the more detailed documents are relevant to the reader of -this introduction depends on their role in the benchmarking process.

A writer of benchmarks has to understand the bench language -itself. A beginner to bench should read the more informally written -bench language introduction first. Having digested this the -formal bench language specification should become -understandable. A writer experienced with bench may only need this -last document from time to time, to refresh her memory.
A user of benchmark suites written in the bench language -has to know which tools are available for use. -At the bottom level sits the package bench, providing the -basic facilities to read and execute files containing benchmarks -written in the bench language, and to manipulate benchmark results.

HISTORICAL NOTES

This module and package have been derived from Jeff Hobbs' -tclbench application for the benchmarking of the Tcl core and -its ancestor "runbench.tcl".

Bugs, Ideas, Feedback

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

Keywords

bench language, benchmark, performance, testing

Category

Benchmark tools

Copyright

DELETED embedded/www/tcllib/files/modules/bench/bench_lang_intro.html Index: embedded/www/tcllib/files/modules/bench/bench_lang_intro.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench_lang_intro.html +++ /dev/null @@ -1,253 +0,0 @@ - -

- -

bench_lang_intro(n) 1.0 tcllib "Benchmarking/Performance tools"

Name

bench_lang_intro - bench language introduction

Table Of Contents
Description -
- Fundamentals
- Basics
- Pre- and postprocessing
- Advanced pre- and postprocessing
-
FURTHER READING
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

This document is an informal introduction to version 1 of the bench -language based on a multitude of examples. After reading this a -benchmark writer should be ready to understand the formal -bench language specification.

Fundamentals

In the broadest terms possible the bench language is -essentially Tcl, plus a number of commands to support the declaration -of benchmarks. -A document written in this language is a Tcl script and has the same -syntax.

Basics

One of the most simplest benchmarks which can be written in bench is

-bench -desc LABEL -body {
-    set a b
-}
-

This code declares a benchmark named LABEL which measures the -time it takes to assign a value to a variable. The Tcl code doing this -assignment is the -body of the benchmark.

Pre- and postprocessing

Our next example demonstrates how to declare initialization and -cleanup code, i.e. code computing information for the use of -the -body, and for releasing such resources after the -measurement is done. -They are the -pre- and the -post-body, respectively.

In our example, directly drawn from the benchmark suite of Tcllib's -aes package, the concrete initialization code constructs the -key schedule used by the encryption command whose speed we measure, -and the cleanup code releases any resources bound to that schedule.

-bench -desc "AES-${len} ECB encryption core" -pre {
-    set key [aes::Init ecb $k $i]
-} -body {
-    aes::Encrypt $key $p
-} -post {
-    aes::Final $key
-}
-

Advanced pre- and postprocessing

Our last example again deals with initialization and cleanup code. To -see the difference to the regular initialization and cleanup discussed -in the last section it is necessary to know a bit more about how bench -actually measures the speed of the the -body.

Instead of running the -body just once the system actually -executes the -body several hundred times and then returns the -average of the found execution times. This is done to remove -environmental effects like machine load from the result as much as -possible, with outliers canceling each other out in the average.

The drawback of doing things this way is that when we measure -operations which are not idempotent we will most likely not measure -the time for the operation we want, but of the state(s) the system is -in after the first iteration, a mixture of things we have no interest -in.

Should we wish, for example, to measure the time it takes to include -an element into a set, with the element not yet in the set, and the -set having specific properties like being a shared Tcl_Obj, then the -first iteration will measure the time for this. However all -subsequent iterations will measure the time to include an element -which is already in the set, and the Tcl_Obj holding the set will not -be shared anymore either. In the end the timings taken for the several -hundred iterations of this state will overwhelm the time taken from -the first iteration, the only one which actually measured what we -wanted.

The advanced initialization and cleanup codes, -ipre- and the --ipost-body respectively, are present to solve this very -problem. While the regular initialization and cleanup codes are -executed before and after the whole series of iterations the advanced -codes are executed before and after each iteration of the body, -without being measured themselves. This allows them to bring the -system into the exact state the body wishes to measure.

Our example, directly drawn from the benchmark suite of Tcllib's -struct::set package, is for exactly the example we used -above to demonstrate the necessity for the advanced initialization and -cleanup. Its concrete initialization code constructs a variable -refering to a set with specific properties (The set has a string -representation, which is shared) affecting the speed of the inclusion -command, and the cleanup code releases the temporary variables created -by this initialization.

-bench -desc "set include, missing <SC> x$times $n" -ipre {
-    set A $sx($times,$n)
-    set B $A
-} -body {
-    struct::set include A x
-} -ipost {
-    unset A B
-}
-

Bugs, Ideas, Feedback

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

Keywords

bench language, benchmark, examples, performance, testing

Category

Benchmark tools

Copyright

DELETED embedded/www/tcllib/files/modules/bench/bench_lang_spec.html Index: embedded/www/tcllib/files/modules/bench/bench_lang_spec.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench_lang_spec.html +++ /dev/null @@ -1,233 +0,0 @@ - -

- -

bench_lang_spec(n) 1.0 tcllib "Documentation tools"

Name

bench_lang_spec - bench language specification

Table Of Contents
Synopsis
Description
Commands
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

bench_rm path...
bench_tmpfile
bench options...

Description

This document specifies both names and syntax of all the commands -which together are the bench language, version 1. -As this document is intended to be a reference the commands are listed -in alphabetical order, and the descriptions are relatively short. -A beginner should read the more informally written -bench language introduction first.

Commands

bench_rm path...

This command silently removes the files specified as its arguments and -then returns the empty string as its result. -The command is trusted, there is no checking if the specified -files are outside of whatever restricted area the benchmarks are run -in.

bench_tmpfile

This command returns the path to a bench specific unique temporary -file. The uniqueness means that multiple calls will return different -paths. While the path may exist from previous runs, the command itself -does not create aynthing.

The base location of the temporary files is platform dependent:

Unix, and indeterminate platform: "/tmp"
Windows: $TEMP
Anything else: The current working directory.

bench options...

This command declares a single benchmark. Its result is the empty -string. All parts of the benchmark are declared via options, and their -values. The options can occur in any order. The accepted options are:

-body script

The argument of this option declares the body of the benchmark, the -Tcl script whose performance we wish to measure. This option, and --desc, are the two required parts of each benchmark.

-desc msg

The argument of this option declares the name of the benchmark. It has -to be unique, or timing data from different benchmarks will be mixed -together.

Beware! This requirement is not checked when benchmarks are -executed, and the system will silently produce bogus data. This -option, and -body, are the two required parts of each -benchmark.

-ipost script

The argument of this option declares a script which is run immediately -after each iteration of the body. Its responsibility is to -release resources created by the body, or -ipre-bodym which -we do not wish to live into the next iteration.

-ipre script

The argument of this option declares a script which is run immediately -before each iteration of the body. Its responsibility is to -create the state of the system expected by the body so that we measure -the right thing.

-iterations num

The argument of this option declares the maximum number of times to -run the -body of the benchmark. During execution this and the -global maximum number of iterations are compared and the smaller of -the two values is used.

This option should be used only for benchmarks which are expected or -known to take a long time per run. I.e. reduce the number of times -they are run to keep the overall time for the execution of the whole -benchmark within manageable limits.

-post script

The argument of this option declares a script which is run -after all iterations of the body have been run. Its -responsibility is to release resources created by the body, -or -pre-body.

-pre script

The argument of this option declares a script which is run -before any of the iterations of the body are run. Its -responsibility is to create whatever resources are needed by the body -to run without failing.

Bugs, Ideas, Feedback

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

Keywords

bench language, benchmark, performance, specification, testing

Category

Benchmark tools

Copyright

DELETED embedded/www/tcllib/files/modules/bench/bench_read.html Index: embedded/www/tcllib/files/modules/bench/bench_read.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench_read.html +++ /dev/null @@ -1,184 +0,0 @@ - -

- -

bench::in(n) 0.1 tcllib "Benchmarking/Performance tools"

Name

bench::in - bench::in - Reading benchmark results

Table Of Contents
Synopsis
Description
PUBLIC API
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require csv
package require bench::in ?0.1?

::bench::in::read file

Description

This package provides a command for reading benchmark results from -files, sockets, etc.

A reader interested in the creation, processing or writing of such -results should go and read -bench - Processing benchmark suites instead.

If the bench language itself is the actual interest please start with -the bench language introduction and then proceed from there -to the formal bench language specification.

PUBLIC API

::bench::in::read file

This command reads a benchmark result from the specified file -and returns it as its result. The command understands the three -formats created by the commands

bench::out::raw: Provided by package bench.
bench::out::csv: Provided by package bench::out::csv.
bench::out::text: Provided by package bench::out::text.

and automatically detects which format is used by the input file.

Bugs, Ideas, Feedback

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

Keywords

benchmark, csv, formatting, human readable, parsing, performance, reading, testing, text

Category

Benchmark tools

Copyright

DELETED embedded/www/tcllib/files/modules/bench/bench_wcsv.html Index: embedded/www/tcllib/files/modules/bench/bench_wcsv.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench_wcsv.html +++ /dev/null @@ -1,176 +0,0 @@ - -

- -

bench::out::csv(n) 0.1.2 tcllib "Benchmarking/Performance tools"

Name

bench::out::csv - bench::out::csv - Formatting benchmark results as CSV

Table Of Contents
Synopsis
Description
PUBLIC API
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require bench::out::csv ?0.1.2?

::bench::out::csv bench_result

Description

This package provides commands for fomatting of benchmark results into -a CSV table importable by spread sheets.

A reader interested in the generation or processing of such results should -go and read bench - Processing benchmark suites instead.

If the bench language itself is the actual interest please start with -the bench language introduction and then proceed from there -to the formal bench language specification.

PUBLIC API

::bench::out::csv bench_result

This command formats the specified benchmark result for output to a -file, socket, etc. This specific command generates CSV data importable -by spread sheets.

For other formatting styles see the packages bench and -bench::out::text which provide commands to format benchmark -results in raw form, or for human consumption, respectively.

Bugs, Ideas, Feedback

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

Keywords

benchmark, csv, formatting, performance, testing

Category

Benchmark tools

Copyright

DELETED embedded/www/tcllib/files/modules/bench/bench_wtext.html Index: embedded/www/tcllib/files/modules/bench/bench_wtext.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench_wtext.html +++ /dev/null @@ -1,176 +0,0 @@ - -

- -

bench::out::text(n) 0.1.2 tcllib "Benchmarking/Performance tools"

Name

bench::out::text - bench::out::text - Formatting benchmark results as human readable text

Table Of Contents
Synopsis
Description
PUBLIC API
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require bench::out::text ?0.1.2?

::bench::out::text bench_result

Description

This package provides commands for fomatting of benchmark results into -human readable text.

A reader interested in the generation or processing of such results should -go and read bench - Processing benchmark suites instead.

If the bench language itself is the actual interest please start with -the bench language introduction and then proceed from there -to the formal bench language specification.

PUBLIC API

::bench::out::text bench_result

This command formats the specified benchmark result for output to a -file, socket, etc. This specific command generates human readable -text.

For other formatting styles see the packages bench and -bench::out::csv which provide commands to format benchmark -results in raw form, or as importable CSV data, respectively.

Bugs, Ideas, Feedback

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

Keywords

benchmark, formatting, human readable, performance, testing, text

Category

Benchmark tools

Copyright

DELETED embedded/www/tcllib/files/modules/bibtex/bibtex.html Index: embedded/www/tcllib/files/modules/bibtex/bibtex.html ================================================================== --- embedded/www/tcllib/files/modules/bibtex/bibtex.html +++ /dev/null @@ -1,259 +0,0 @@ - -

- -

bibtex(n) 0.6 tcllib "bibtex"

Name

bibtex - Parse bibtex files

Table Of Contents
Synopsis
Description
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require bibtex ?0.6?

::bibtex::parse ?options? ?text?
::bibtex::parse text
::bibtex::parse ?-command cmd? -channel chan
::bibtex::parse ?-recordcommand recordcmd? ?-preamblecommand preamblecmd? ?-stringcommand stringcmd? ?-commentcommand commentcmd? ?-progresscommand progresscmd? ?-casesensitivestrings bool? (text | -channel chan)
::bibtex::wait token
::bibtex::destroy token
::bibtex::addStrings token stringdict

Description

This package provides commands for the parsing of bibliographies in -BibTeX format.

::bibtex::parse ?options? ?text?

This is the general form of the command for parsing a -bibliography. Depending on the options used to invoke it it will -either return a token for the parser, or the parsed entries of the -input bibliography. Instead of performing an immediate parse returning -a predefined format the command can also enter an event-based parsing -style where all relevant entries in the input are reported through -callback commands, in the style of SAX.

::bibtex::parse text

In this form the command will assume that the specified text is -a bibliography in BibTeX format, parse it, and then return a list -containing one element per record found in the bibliography. Note that -comments, string definitions, preambles, etc. will not show up in the -result. Each element will be a list containing record type, -bibliography key and record data, in this order. The record data will -be a dictionary, its keys the keys of the record, with the associated -values.

::bibtex::parse ?-command cmd? -channel chan

In this form the command will reads the bibliography from the -specified Tcl channel chan and then returns the same data -structure as described above.

If however the option -command is specified the result will be a -handle for the parser instead and all processing will be incremental -and happen in the background. When the input has been exhausted the -callback cmd will be invoked with the result of the parse. The -exact definition for the callback is

cmd token parseresult: The parse result will have the structure explained above, for the -simpler forms of the parser.

Note that the parser will not close the channel after it -has exhausted it. This is still the responsibility of the user of the -parser.

::bibtex::parse ?-recordcommand recordcmd? ?-preamblecommand preamblecmd? ?-stringcommand stringcmd? ?-commentcommand commentcmd? ?-progresscommand progresscmd? ?-casesensitivestrings bool? (text | -channel chan)

This is the most low-level form for the parser. The returned result -will be a handle for the parser. During processing it will invoke the -invoke the specified callback commands for each type of data found in -the bibliography.

The processing will be incremental and happen in the background if, -and only if a Tcl channel chan is specified. For a text -the processing will happen immediately and all callbacks will be -invoked before the command itself returns.

The callbacks, i.e. *cmd, are all command prefixes and will be -invoked with additional arguments appended to them. The meaning of the -arguments depends on the callback and is explained below. The first -argument will however always be the handle of the parser invoking the -callback.

-casesensitivestrings: This option takes a boolean value. When set string macro processing -becomes case-sensitive. The default is case-insensitive string macro -processing.
recordcmd token type key recorddict: This callback is invoked whenever the parser detects a bibliography -record in the input. Its arguments are the record type, the -bibliography key for the record, and a dictionary containing the keys -and values describing the record. Any string macros known to the -parser have already been expanded.
preamblecmd token preambletext: This callback is invoked whenever the parser detects an @preamble -block in the input. The only additional argument is the text found in -the preamble block. By default such entries are ignored.
stringcmd token stringdict: This callback is invoked whenever the parser detects an @string-based -macro definition in the input. The argument is a dictionary with the -macro names as keys and their replacement strings as values. By -default such definitions are added to the parser state for use in -future bibliography records.
commentcmd token commenttext: This callback is invoked whenever the parser detects a comment in the -input. The only additional argument is the comment text. By default -such entries are ignored.
progresscmd token percent: This callback is invoked during processing to tell the user about the -progress which has been made. Its argument is the percentage of data -processed, as integer number between 0 and 100. -In the case of incremental processing the perecentage will always be --1 as the total number of entries is not known beforehand.

::bibtex::wait token

This command waits for the parser represented by the token to -complete and then returns. The returned result is the empty string.

::bibtex::destroy token

This command cleans up all internal state associated with the parser -represented by the handle token, effectively destroying it. This -command can be called from within the parser callbacks to terminate -processing.

::bibtex::addStrings token stringdict

This command adds the macro definitions stored in the -dictionary stringdict to the parser represented -by the handle token.

The dictionary keys are the macro names and the values their -replacement strings. This command has the correct signature for use as -a -stringcommand callback in an invokation of the command -::bibtex::parse.

Bugs, Ideas, Feedback

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

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

Keywords

bibliography, bibtex, parsing, text processing

Category

Text processing

Copyright

DELETED embedded/www/tcllib/files/modules/blowfish/blowfish.html Index: embedded/www/tcllib/files/modules/blowfish/blowfish.html ================================================================== --- embedded/www/tcllib/files/modules/blowfish/blowfish.html +++ /dev/null @@ -1,264 +0,0 @@ - -

- -

blowfish(n) 1.0.3 tcllib "Blowfish Block Cipher"

Name

blowfish - Implementation of the Blowfish block cipher

Table Of Contents
Synopsis
Description
COMMANDS
PROGRAMMING INTERFACE
MODES OF OPERATION
EXAMPLES
REFERENCES
AUTHORS
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require blowfish ?1.0.4?

::blowfish::blowfish ?-mode [ecb|cbc]? ?-dir [encrypt|decrypt]? -key keydata ?-iv vector? ?-out channel? ?-chunksize size? ?-pad padchar? [ -in channel | ?--? data ]
::blowfish::Init mode keydata iv
::blowfish::Encrypt Key data
::blowfish::Decrypt Key data
::blowfish::Reset Key iv
::blowfish::Final Key

Description

This package is an implementation in Tcl of the Blowfish algorithm -developed by Bruce Schneier [1]. Blowfish is a 64-bit block cipher -designed to operate quickly on 32 bit architectures and accepting a -variable key length. This implementation supports ECB and CBC mode -blowfish encryption.

COMMANDS

::blowfish::blowfish ?-mode [ecb|cbc]? ?-dir [encrypt|decrypt]? -key keydata ?-iv vector? ?-out channel? ?-chunksize size? ?-pad padchar? [ -in channel | ?--? data ]

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

The -key option must be given. This parameter takes a binary -string of variable length and is used to generate the blowfish -key schedule. You should be aware that creating a key -schedule is quite an expensive operation in blowfish so it is worth -reusing the key where possible. See Reset.

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

Blowfish is a 64-bit block cipher. This means that the data must be -provided in units that are a multiple of 8 bytes. The blowfish -command will by default add nul characters to pad the input data to a -multiple of 8 bytes if necessary. The programming api commands will -never add padding and instead will raise an error if the input is not -a multiple of the block size. The -pad option can be used to -change the padding character or to disable padding if the empty string -is provided as the argument.

PROGRAMMING INTERFACE

::blowfish::Init mode keydata iv: Construct a new blowfish key schedule using the specified key data and -the given initialization vector. The initialization vector is not used -with ECB mode but is important for CBC mode. -See MODES OF OPERATION for details about cipher modes.
::blowfish::Encrypt Key data: Use a prepared key acquired by calling Init to encrypt the -provided data. The data argument should be a binary array that is a -multiple of the block size of 8 bytes. The result is a binary -array the same size as the input of encrypted data.
::blowfish::Decrypt Key data: Decipher data using the key. Note that the same key may be used to -encrypt and decrypt data provided that the initialization vector is -reset appropriately for CBC mode.
::blowfish::Reset Key iv: Reset the initialization vector. This permits the programmer to re-use -a key and avoid the cost of re-generating the key schedule where the -same key data is being used multiple times.
::blowfish::Final Key: This should be called to clean up resources associated with Key. -Once this function has been called the key may not be used again.

MODES OF OPERATION

Electronic Code Book (ECB): ECB is the basic mode of all block ciphers. Each block is encrypted -independently and so identical plain text will produce identical -output when encrypted with the same key. Any encryption errors will -only affect a single block however this is vulnerable to known -plaintext attacks.
Cipher Block Chaining (CBC): CBC mode uses the output of the last block encryption to affect the -current block. An initialization vector of the same size as the cipher -block size is used to handle the first block. The initialization -vector should be chosen randomly and transmitted as the first block of -the output. Errors in encryption affect the current block and the next -block after which the cipher will correct itself. CBC is the most -commonly used mode in software encryption.

EXAMPLES

-% blowfish::blowfish -hex -mode ecb -dir encrypt -key secret01 "hello, world!"
-d0d8f27e7a374b9e2dbd9938dd04195a
-

- set Key [blowfish::Init cbc $eight_bytes_key_data $eight_byte_iv]
- append ciphertext [blowfish::Encrypt $Key $plaintext]
- append ciphertext [blowfish::Encrypt $Key $additional_plaintext]
- blowfish::Final $Key
-

REFERENCES

Schneier, B. "Applied Cryptography, 2nd edition", 1996, - ISBN 0-471-11709-9, pub. John Wiley & Sons.

AUTHORS

Frank Pilhofer, Pat Thoyts

Bugs, Ideas, Feedback

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

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

Keywords

block cipher, blowfish, cryptography, encryption, security

Category

Hashes, checksums, and encryption

Copyright

DELETED embedded/www/tcllib/files/modules/cache/async.html Index: embedded/www/tcllib/files/modules/cache/async.html ================================================================== --- embedded/www/tcllib/files/modules/cache/async.html +++ /dev/null @@ -1,239 +0,0 @@ - -

- -

cache::async(n) 0.3.1 tcllib "In-memory caches"

Name

cache::async - Asynchronous in-memory cache

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Copyright

Synopsis

package require Tcl 8.4
package require cache::async ?0.3.1?

::cache::async objectName commandprefix ?options...?
objectName get key donecmdprefix
objectName set key value
objectName unset key
objectName exists key
objectName clear ?key?

Description

This package provides objects which cache data in memory, and operate -asynchronously with regard to request and responses. The objects are -agnostic with regard to cache keys and values, and unknown methods are -delegated to the provider of cached data. These two properties make it -easy to use caches as a facade for any data provider.

API

The package exports a class, cache::async, as specified -below.

::cache::async objectName commandprefix ?options...?

The command creates a new cache object with an associated -global Tcl command whose name is objectName. This command may -be used to invoke various operations on the object.

The commandprefix is the action to perform when an user asks for -data in the cache and the cache doesn't yet know about the key. When -run the commandprefix is given three additional arguments, the string -get, the key requested, and the cache object itself, in the -form of its object command, in this order. The execution of the action -is done in an idle-handler, decoupling it from the original request.

The only supported option is

-full-async-results: This option defines the behaviour of the cache for when requested keys -are known to the cache at the time of get request. By default -such requeste are responded to asynchronously as well. Setting this -option to false forces the cache to respond to them -synchronuously, although still through the specified callback.

The object commands created by the class commands above have -the form:

objectName get key donecmdprefix

This method requests the data for the key from the cache. If the -data is not yet known the command prefix specified during construction -of the cache object is used to ask for this information.

Whenever the information is/becomes available the donecmdprefix -will be run to transfer the result to the caller. This command prefix -is invoked with either 2 or 3 arguments, i.e.

The string set, the key, and the value.
The string unset, and the key.

These two possibilities are used to either signal the value for the -key, or that the key has no value defined for it. The -latter is distinct from the cache not knowing about the key.

For a cache object configured to be fully asynchronous (default) the -donecmdprefix is always run in an idle-handler, decoupling it -from the request. Otherwise the callback will be invoked synchronously -when the key is known to the cache at the time of the -invokation.

Another important part of the cache's behaviour, as it is asynchronous -it is possible that multiple get requests are issued for the -same key before it can respond. In that case the cache will -issue only one data request to the provider, for the first of these, -and suspend the others, and then notify all of them when the data -becomes available.

objectName set key value

objectName unset key

These two methods are provided to allow users of the cache to make -keys known to the cache, as either having a value, or as -undefined.

It is expected that the data provider (see commandprefix of the -constructor) uses them in response to data requests for unknown keys.

Note how this matches the cache's own API towards its caller, calling -the donecmd of get-requests issued to itself with -either "set key value" or "unset key", versus issuing -get-requests to its own provider with itself in the place of -the donecmd, expecting to be called with either "set key value" -or "unset key".

This also means that these methods invoke the donecmd of all -get-requests waiting for information about the modified -key.

objectName exists key

This method queries the cache for knowledge about the key and -returns a boolean value. The result is true if the key is -known, and false otherwise.

objectName clear ?key?

This method resets the state of either the specified key or of -all keys known to the cache, making it unkown. This forces future -get-requests to reload the information from the provider.

Bugs, Ideas, Feedback

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

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

Keywords

asynchronous, cache, callback, synchronous

Copyright

DELETED embedded/www/tcllib/files/modules/clock/iso8601.html Index: embedded/www/tcllib/files/modules/clock/iso8601.html ================================================================== --- embedded/www/tcllib/files/modules/clock/iso8601.html +++ /dev/null @@ -1,168 +0,0 @@ - -

- -

clock_iso8601(n) 0.1 tcllib "Date/Time Utilities"

Name

clock_iso8601 - Parsing ISO 8601 dates/times

Table Of Contents
Synopsis
Description
Bugs, Ideas, Feedback
Category

Synopsis

package require Tcl 8.5
package require clock::iso8601 ?0.1?

::clock::iso8601 parse_date date options...
::clock::iso8601 parse_time time options...

Description

This package provides functionality to parse dates and times in -ISO 8601 format.

::clock::iso8601 parse_date date options...

This command parses an ISO8601 date string in an unknown variant and -returns the given date/time in seconds since epoch.

The acceptable options are --base, --gmt, --locale, and --timezone -of the builtin command clock scan.

::clock::iso8601 parse_time time options...

This command parses a full ISO8601 timestamp string (date and time) in -an unknown variant and returns the given time in seconds since epoch.

The acceptable options are --base, --gmt, --locale, and --timezone -of the builtin command clock scan.

Bugs, Ideas, Feedback

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

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

Category

Text processing

DELETED embedded/www/tcllib/files/modules/clock/rfc2822.html Index: embedded/www/tcllib/files/modules/clock/rfc2822.html ================================================================== --- embedded/www/tcllib/files/modules/clock/rfc2822.html +++ /dev/null @@ -1,153 +0,0 @@ - -

- -

clock_rfc2822(n) 0.1 tcllib "Date/Time Utilities"

Name

clock_rfc2822 - Parsing ISO 8601 dates/times

Table Of Contents
Synopsis
Description
Bugs, Ideas, Feedback
Category

Synopsis

package require Tcl 8.5
package require clock::rfc2822 ?0.1?

::clock::rfc2822 parse_date date

Description

This package provides functionality to parse dates in -RFC 2822 format.

::clock::rfc2822 parse_date date: This command parses an RFC2822 date string and returns -the given date in seconds since epoch. An error is thrown -if the command is unable to parse the date.

Bugs, Ideas, Feedback

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

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

Category

Text processing

DELETED embedded/www/tcllib/files/modules/cmdline/cmdline.html Index: embedded/www/tcllib/files/modules/cmdline/cmdline.html ================================================================== --- embedded/www/tcllib/files/modules/cmdline/cmdline.html +++ /dev/null @@ -1,291 +0,0 @@ -

- -

cmdline(n) 1.5 tcllib "Command line and option processing"

Name

cmdline - Procedures to process command lines and options.

Table Of Contents
Synopsis
Description
::argv handling
API -
- Error Codes
-
EXAMPLES
Bugs, Ideas, Feedback
Keywords
Category

Synopsis

package require Tcl 8.2
package require cmdline ?1.3.3?

::cmdline::getopt argvVar optstring optVar valVar
::cmdline::getKnownOpt argvVar optstring optVar valVar
::cmdline::getoptions arglistVar optlist ?usage?
::cmdline::getKnownOptions arglistVar optlist ?usage?
::cmdline::usage optlist ?usage?
::cmdline::getfiles patterns quiet
::cmdline::getArgv0

Description

This package provides commands to parse command lines and options.

::argv handling

One of the most common variables this package will be used with is -::argv, which holds the command line of the current -application. This variable has a companion ::argc which is -initialized to the number of elements in ::argv at the beginning -of the application.

The commands in this package will not modify the ::argc -companion when called with ::argv. Keeping the value consistent, -if such is desired or required, is the responsibility of the caller.

API

::cmdline::getopt argvVar optstring optVar valVar

This command works in a fashion like the standard C based getopt -function. Given an option string and a pointer to an array of args -this command will process the first argument and return info on how to -proceed. The command returns 1 if an option was found, 0 if no more -options were found, and -1 if an error occurred.

argvVar contains the name of the list of arguments to -process. If options are found the list is modified and the processed -arguments are removed from the start of the list.

optstring contains a list of command options that the -application will accept. If the option ends in ".arg" the command -will use the next argument as an argument to the option, or extract it -from the current argument, if it is of the form "option=value". -Otherwise the option is a boolean that is set to 1 if present.

optVar refers to the variable the command will store the found -option into (without the leading '-' and without the .arg extension).

valVar refers to the variable to store either the value for the -specified option into upon success or an error message in the case of -failure. The stored value comes from the command line for .arg -options, otherwise the value is 1.

::cmdline::getKnownOpt argvVar optstring optVar valVar

Like ::cmdline::getopt, but ignores any unknown options in the -input.

::cmdline::getoptions arglistVar optlist ?usage?

Processes the set of command line options found in the list variable -named by arglistVar and fills in defaults for those not -specified. This also generates an error message that lists the -allowed flags if an incorrect flag is specified. The optional -usage-argument contains a string to include in front of the -generated message. If not present it defaults to "options:".

optlist contains a list of lists where each element specifies an -option in the form: flag default comment.

If flag ends in ".arg" then the value is taken from the command -line. Otherwise it is a boolean and appears in the result if present -on the command line. If flag ends in ".secret", it will not be -displayed in the usage.

The options -?, -help, and -- are -implicitly understood. The first two abort option processing by -throwing an error and force the generation of the usage message, -whereas the the last aborts option processing without an error, -leaving all arguments coming after for regular processing, even if -starting with a dash.

The result of the command is a dictionary mapping all options to their -values, be they user-specified or defaults.

::cmdline::getKnownOptions arglistVar optlist ?usage?

Like ::cmdline::getoptions, but ignores any unknown options in the -input.

::cmdline::usage optlist ?usage?

Generates and returns an error message that lists the allowed -flags. optlist is defined as for -::cmdline::getoptions. The optional usage-argument -contains a string to include in front of the generated message. If not -present it defaults to "options:".

::cmdline::getfiles patterns quiet

Given a list of file patterns this command computes the set of -valid files. On windows, file globbing is performed on each argument. -On Unix, only file existence is tested. If a file argument produces -no valid files, a warning is optionally generated (set quiet to -true).

This code also uses the full path for each file. If not given it -prepends the current working directory to the filename. This ensures -that these files will never conflict with files in a wrapped zip -file. The last sentence refers to the pro-tools.

::cmdline::getArgv0

This command returns the "sanitized" version of argv0. It will -strip off the leading path and removes the extension ".bin". The -latter is used by the pro-apps because they must be wrapped by a shell -script.

Error Codes

Starting with version 1.5 all errors thrown by the package have a -proper ::errorCode for use with Tcl's try command. This -code always has the word CMDLINE as its first element.

EXAMPLES

-        package require Tcl 8.5
-        package require try         ;# Tcllib.
-        package require cmdline 1.5 ;# First version with proper error-codes.
-        # Notes:
-        # - Tcl 8.6+ has 'try' as a builtin command and therefore does not
-        #   need the 'try' package.
-        # - Before Tcl 8.5 we cannot support 'try' and have to use 'catch'.
-        #   This then requires a dedicated test (if) on the contents of
-        #   ::errorCode to separate the CMDLINE USAGE signal from actual errors.
-        set options {
-            {a          "set the atime only"}
-            {m          "set the mtime only"}
-            {c          "do not create non-existent files"}
-            {r.arg  ""  "use time from ref_file"}
-            {t.arg  -1  "use specified time"}
-        }
-        set usage ": MyCommandName \[options] filename ...\noptions:"
-        try {
-            array set params [::cmdline::getoptions argv $options $usage]
-        } trap {CMDLINE USAGE} {msg o} {
-            # Trap the usage signal, print the message, and exit the application.
-            # Note: Other errors are not caught and passed through to higher levels!
-	    puts $msg
-	    exit 1
-        }
-        if {  $params(a) } { set set_atime "true" }
-        set has_t [expr {$params(t) != -1}]
-        set has_r [expr {[string length $params(r)] > 0}]
-        if {$has_t && $has_r} {
-            return -code error "Cannot specify both -r and -t"
-        } elseif {$has_t} {
-	    ...
-        }
-

This example, taken (and slightly modified) from the package -fileutil, shows how to use cmdline. First, a list of -options is created, then the 'args' list is passed to cmdline for -processing. Subsequently, different options are checked to see if -they have been passed to the script, and what their value is.

Bugs, Ideas, Feedback

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

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

Keywords

argument processing, argv, argv0, cmdline processing, command line processing

Category

Programming tools

DELETED embedded/www/tcllib/files/modules/comm/comm.html Index: embedded/www/tcllib/files/modules/comm/comm.html ================================================================== --- embedded/www/tcllib/files/modules/comm/comm.html +++ /dev/null @@ -1,1040 +0,0 @@ - -

- -

comm(n) 4.6.3 tcllib "Remote communication"

Name

comm - A remote communication facility for Tcl (8.3 and later)

- - -

Description

The comm command provides an inter-interpreter remote -execution facility much like Tk's send(n), except that it uses -sockets rather than the X server for the communication path. As a -result, comm works with multiple interpreters, works on -Windows and Macintosh systems, and provides control over the remote -execution path.

These commands work just like send and winfo interps :

-    ::comm::comm send ?-async? id cmd ?arg arg ...?
-    ::comm::comm interps
-

This is all that is really needed to know in order to use -comm

Commands

The package initializes ::comm::comm as the default chan.

comm names communication endpoints with an id unique -to each machine. Before sending commands, the id of another -interpreter is needed. Unlike Tk's send, comm doesn't -implicitly know the id's of all the interpreters on the system. -The following four methods make up the basic comm interface.

::comm::comm send ?-async? ?-command callback? id cmd ?arg arg ...?: This invokes the given command in the interpreter named by id. The -command waits for the result and remote errors are returned unless the --async or -command option is given. If -async -is given, send returns immediately and there is no further notification of -result. If -command is used, callback specifies a command -to invoke when the result is received. These options are mutually -exclusive. The callback will receive arguments in the form --option value, suitable for array set. -The options are: -id, the comm id of the interpreter that received -the command; -serial, a unique serial for each command sent to a -particular comm interpreter; -chan, the comm channel name; --code, the result code of the command; -errorcode, the -errorcode, if any, of the command; -errorinfo, the errorinfo, if -any, of the command; and -result, the return value of the command. -If connection is lost before a reply is received, the callback will be -invoked with a connection lost message with -code equal to -1. When --command is used, the command returns the unique serial for the -command.
::comm::comm self: Returns the id for this channel.
::comm::comm interps: Returns a list of all the remote id's to which this channel is -connected. comm learns a new remote id when a command -is first issued it, or when a remote id first issues a command -to this comm channel. ::comm::comm ids is an alias for this -method.
::comm::comm connect ?id?: Whereas ::comm::comm send will automatically connect to the -given id, this forces a connection to a remote id without -sending a command. After this, the remote id will appear in -::comm::comm interps.

Eval Semantics

The evaluation semantics of ::comm::comm send are intended to -match Tk's send exactly. This means that comm -evaluates arguments on the remote side.

If you find that ::comm::comm send doesn't work for a -particular command, try the same thing with Tk's send and see if the -result is different. If there is a problem, please report it. For -instance, there was had one report that this command produced an -error. Note that the equivalent send command also produces the -same error.

-    % ::comm::comm send id llength {a b c}
-    wrong # args: should be "llength list"
-    % send name llength {a b c}
-    wrong # args: should be "llength list"
-

The eval hook (described below) can be used to change from -send's double eval semantics to single eval semantics.

Multiple Channels

More than one comm channel (or listener) can be created -in each Tcl interpreter. This allows flexibility to create full and -restricted channels. For instance, hook scripts are specific -to the channel they are defined against.

::comm::comm new chan ?name value ...?: This creates a new channel and Tcl command with the given channel -name. This new command controls the new channel and takes all the -same arguments as ::comm::comm. Any remaining arguments are -passed to the config method. The fully qualified channel -name is returned.
::comm::comm channels: This lists all the channels allocated in this Tcl interpreter.

The default configuration parameters for a new channel are:

-    "-port 0 -local 1 -listen 0 -silent 0"
-

The default channel ::comm::comm is created with:

-    "::comm::comm new ::comm::comm -port 0 -local 1 -listen 1 -silent 0"
-

Channel Configuration

The config method acts similar to fconfigure in that it -sets or queries configuration variables associated with a channel.

::comm::comm config
::comm::comm config name
::comm::comm config ?name value ...?: When given no arguments, config returns a list of all variables -and their value With one argument, config returns the value of -just that argument. With an even number of arguments, the given -variables are set to the given values.

These configuration variables can be changed (descriptions of them are -elsewhere in this manual page):

-listen ?0|1?
-local ?0|1?
-port ?port?
-silent ?0|1?
-socketcmd ?commandname?
-interp ?interpreter?
-events ?eventlist?

These configuration variables are read only:

-chan chan
-serial n
-socket sockIn

When config changes the parameters of an existing channel (with -the exception of -interp and -events), it closes and -reopens the listening socket. -An automatically assigned channel id will change when this -happens. -Recycling the socket is done by invoking ::comm::comm abort, -which causes all active sends to terminate.

Id/port Assignments

comm uses a TCP port for endpoint id. The -interps (or ids) method merely lists all the TCP ports -to which the channel is connected. By default, each channel's -id is randomly assigned by the operating system (but usually -starts at a low value around 1024 and increases each time a new socket -is opened). This behavior is accomplished by giving the --port config option a value of 0. Alternately, a specific -TCP port number may be provided for a given channel. As a special -case, comm contains code to allocate a a high-numbered TCP port -(>10000) by using -port {}. Note that a channel won't be -created and initialized unless the specific port can be allocated.

As a special case, if the channel is configured with --listen 0, then it will not create a listening socket and -will use an id of 0 for itself. Such a channel is only good -for outgoing connections (although once a connection is established, -it can carry send traffic in both directions). -As another special case, if the channel is configured with --silent 0, then the listening side will ignore connection -attempts where the protocol negotiation phase failed, instead of -throwing an error.

Execution Environment

A communication channel in its default configuration will use the -current interpreter for the execution of all received scripts, and of -the event scripts associated with the various hooks.

This insecure setup can be changed by the user via the two options --interp, and -events.

When -interp is set all received scripts are executed in the -slave interpreter specified as the value of the option. This -interpreter is expected to exist before configuration. I.e. it is the -responsibility of the user to create it. However afterward the -communication channel takes ownership of this interpreter, and will -destroy it when the communication channel is destroyed. -Note that reconfiguration of the communication channel to either a -different interpreter or the empty string will release the ownership -without destroying the previously configured interpreter. The -empty string has a special meaning, it restores the default behaviour -of executing received scripts in the current interpreter.

Also of note is that replies and callbacks (a special form of -reply) are not considered as received scripts. They are -trusted, part of the internal machinery of comm, and therefore always -executed in the current interpreter.

Even if an interpreter has been configured as the execution -environment for received scripts the event scripts associated with the -various hooks will by default still be executed in the current -interpreter. To change this use the option -events to declare -a list of the events whose scripts should be executed in the declared -interpreter as well. The contents of this option are ignored if the -communication channel is configured to execute received scripts in the -current interpreter.

Remote Interpreters

By default, each channel is restricted to accepting connections from -the local system. This can be overridden by using the --local 0 configuration option For such channels, the -id parameter takes the form { id host }.

WARNING: The host must always be specified in the same -form (e.g., as either a fully qualified domain name, plain hostname or -an IP address).

Closing Connections

These methods give control over closing connections:

::comm::comm shutdown id

This closes the connection to id, aborting all outstanding -commands in progress. Note that nothing prevents the connection from -being immediately reopened by another incoming or outgoing command.

::comm::comm abort

This invokes shutdown on all open connections in this comm channel.

::comm::comm destroy

This aborts all connections and then destroys the this comm channel -itself, including closing the listening socket. Special code allows -the default ::comm::comm channel to be closed such that the -::comm::comm command it is not destroyed. Doing so closes the -listening socket, preventing both incoming and outgoing commands on -the channel. This sequence reinitializes the default channel:

-    "::comm::comm destroy; ::comm::comm new ::comm::comm"
-

When a remote connection is lost (because the remote exited or called -shutdown), comm can invoke an application callback. -This can be used to cleanup or restart an ancillary process, for -instance. See the lost callback below.

Callbacks

This is a mechanism for setting hooks for particular events:

::comm::comm hook event ?+? ?script?

This uses a syntax similar to Tk's bind command. Prefixing -script with a + causes the new script to be appended. -Without this, a new script replaces any existing script. When -invoked without a script, no change is made. In all cases, the new -hook script is returned by the command.

When an event occurs, the script associated with it is -evaluated with the listed variables in scope and available. The -return code (not the return value) of the script is commonly -used decide how to further process after the hook.

Common variables include:

chan: the name of the comm channel (and command)
id: the id of the remote in question
fid: the file id for the socket of the connection

These are the defined events:

connecting

Variables: -chan, id

This hook is invoked before making a connection to the remote named in -id. An error return (via error) will abort the connection -attempt with the error. Example:

-    % ::comm::comm hook connecting {
-        if {[string match {*[02468]} $id]} {
-            error "Can't connect to even ids"
-        }
-    }
-    % ::comm::comm send 10000 puts ok
-    Connect to remote failed: Can't connect to even ids
-    %
-

connected

Variables: -chan, fid, id, host, and port.

This hook is invoked immediately after making a remote connection to -id, allowing arbitrary authentication over the socket named by -fid. An error return (via error ) will close the -connection with the error. host and port are merely -extracted from the id; changing any of these will have no effect -on the connection, however. It is also possible to substitute and -replace fid.

incoming

Variables: -chan, fid, addr, and remport.

Hook invoked when receiving an incoming connection, allowing arbitrary -authentication over socket named by fid. An error return (via -error) will close the connection with the error. Note that the -peer is named by remport and addr but that the remote -id is still unknown. Example:

-    ::comm::comm hook incoming {
-        if {[string match 127.0.0.1 $addr]} {
-            error "I don't talk to myself"
-        }
-    }
-

eval

Variables: -chan, id, cmd, and buffer.

This hook is invoked after collecting a complete script from a remote -but before evaluating it. This allows complete control over -the processing of incoming commands. cmd contains either -send or async. buffer holds the script to -evaluate. At the time the hook is called, $chan remoteid is -identical in value to id.

By changing buffer, the hook can change the script to be -evaluated. The hook can short circuit evaluation and cause a value to -be immediately returned by using return result (or, from -within a procedure, return -code return result). An -error return (via error) will return an error result, as is if -the script caused the error. Any other return will evaluate the -script in buffer as normal. For compatibility with 3.2, -break and return -code break result is supported, -acting similarly to return {} and return -code return -result.

Examples:

augmenting a command

-    % ::comm::comm send [::comm::comm self] pid
-    5013
-    % ::comm::comm hook eval {puts "going to execute $buffer"}
-    % ::comm::comm send [::comm::comm self] pid
-    going to execute pid
-    5013
-

short circuiting a command

-    % ::comm::comm hook eval {puts "would have executed $buffer"; return 0}
-    % ::comm::comm send [::comm::comm self] pid
-    would have executed pid
-    0
-

Replacing double eval semantics

-    % ::comm::comm send [::comm::comm self] llength {a b c}
-    wrong # args: should be "llength list"
-    % ::comm::comm hook eval {return [uplevel #0 $buffer]}
-    return [uplevel #0 $buffer]
-    % ::comm::comm send [::comm::comm self] llength {a b c}
-    3
-

Using a slave interpreter

-    % interp create foo
-    % ::comm::comm hook eval {return [foo eval $buffer]}
-    % ::comm::comm send [::comm::comm self] set myvar 123
-    123
-    % set myvar
-    can't read "myvar": no such variable
-    % foo eval set myvar
-    123
-

Using a slave interpreter (double eval)

-    % ::comm::comm hook eval {return [eval foo eval $buffer]}
-

Subverting the script to execute

-    % ::comm::comm hook eval {
-        switch -- $buffer {
-            a {return A-OK}
-            b {return B-OK}
-            default {error "$buffer is a no-no"}
-        }
-    }
-    % ::comm::comm send [::comm::comm self] pid
-    pid is a no-no
-    % ::comm::comm send [::comm::comm self] a
-    A-OK
-

reply

Variables: -chan, id, buffer, ret, and return().

This hook is invoked after collecting a complete reply script from a -remote but before evaluating it. This allows complete -control over the processing of replies to sent commands. The reply -buffer is in one of the following forms

return result
return -code code result
return -code code -errorinfo info -errorcode ecode msg

For safety reasons, this is decomposed. The return result is in -ret, and the return switches are in the return array:

return(-code)
return(-errorinfo)
return(-errorcode)

Any of these may be the empty string. Modifying these four variables -can change the return value, whereas modifying buffer has no -effect.

callback

Variables: -chan, id, buffer, ret, and return().

Similar to reply, but used for callbacks.

lost

Variables: -chan, id, and reason.

This hook is invoked when the connection to id is lost. Return -value (or thrown error) is ignored. reason is an explanatory -string indicating why the connection was lost. Example:

-    ::comm::comm hook lost {
-        global myvar
-        if {$myvar(id) == $id} {
-            myfunc
-            return
-        }
-    }
-

Unsupported

These interfaces may change or go away in subsequence releases.

::comm::comm remoteid

Returns the id of the sender of the last remote command -executed on this channel. If used by a proc being invoked remotely, -it must be called before any events are processed. Otherwise, another -command may get invoked and change the value.

::comm::comm_send

Invoking this procedure will substitute the Tk send and -winfo interps commands with these equivalents that use -::comm::comm.

-    proc send {args} {
-        eval ::comm::comm send $args
-    }
-    rename winfo tk_winfo
-    proc winfo {cmd args} {
-        if {![string match in* $cmd]} {
-            return [eval [list tk_winfo $cmd] $args]
-        }
-        return [::comm::comm interps]
-    }
-

Security

Starting with version 4.6 of the package an option -socketcmd -is supported, allowing the user of a comm channel to specify which -command to use when opening a socket. Anything which is API-compatible -with the builtin ::socket (the default) can be used.

The envisioned main use is the specification of the tls::socket -command, see package tls, to secure the communication.

-	# Load and initialize tls
-	package require tls
-	tls::init  -cafile /path/to/ca/cert -keyfile ...
-	# Create secured comm channel
-	::comm::comm new SECURE -socketcmd tls::socket -listen 1
-	...
-

The sections Execution Environment and Callbacks -are also relevant to the security of the system, providing means to -restrict the execution to a specific environment, perform additional -authentication, and the like.

Blocking Semantics

There is one outstanding difference between comm and -send. When blocking in a synchronous remote command, send -uses an internal C hook (Tk_RestrictEvents) to the event loop to look -ahead for send-related events and only process those without -processing any other events. In contrast, comm uses the -vwait command as a semaphore to indicate the return message has -arrived. The difference is that a synchronous send will block -the application and prevent all events (including window related ones) -from being processed, while a synchronous ::comm::comm send -will block the application but still allow other events to get -processed. In particular, after idle handlers will fire -immediately when comm blocks.

What can be done about this? First, note that this behavior will come -from any code using vwait to block and wait for an event to -occur. At the cost of multiple channel support, comm could -be changed to do blocking I/O on the socket, giving send-like blocking -semantics. However, multiple channel support is a very useful feature -of comm that it is deemed too important to lose. The remaining -approaches involve a new loadable module written in C (which is -somewhat against the philosophy of comm) One way would be to -create a modified version of the vwait command that allow the -event flags passed to Tcl_DoOneEvent to be specified. For comm, -just the TCL_FILE_EVENTS would be processed. Another way would be to -implement a mechanism like Tk_RestrictEvents, but apply it to the Tcl -event loop (since comm doesn't require Tk). One of these -approaches will be available in a future comm release as an -optional component.

Asynchronous Result Generation

By default the result returned by a remotely invoked command is the -result sent back to the invoker. This means that the result is -generated synchronously, and the server handling the call is blocked -for the duration of the command.

While this is tolerable as long as only short-running commands are -invoked on the server long-running commands, like database queries -make this a problem. One command can prevent the processing requests -of all other clients for an arbitrary period of time.

Before version 4.5 of comm the only solution was to rewrite the server -command to use the Tcl builtin command vwait, or one of its -relatives like tkwait, to open a new event loop which processes -requests while the long-running operation is executed. This however -has its own perils, as this makes it possible to both overflow the Tcl -stack with a large number of event loop, and to have a newer requests -block the return of older ones, as the eventloop have to be unwound in -the order of their creation.

The proper solution is to have the invoked command indicate to -comm that it cannot or will not deliver an immediate, -synchronous result, but will do so later. At that point the framework -can put sending the actual result on hold and continue processing -requests using the main event loop. No blocking, no nesting of event -loops. At some future date the long running operation delivers the -result to comm, via the future object, which is then forwarded to the -invoker as usual.

The necessary support for this solution has been added to comm since -version 4.5, in the form of the new method return_async.

::comm::comm return_async

This command is used by a remotely invoked script to notify the comm -channel which invoked it that the result to send back to the invoker -is not generated synchronously. If this command is not called the -default/standard behaviour of comm is to send the synchronously -generated result of the script itself to the invoker.

The result of return_async is an object. This object, called a -future is where the result of the script has to be delivered to -when it becomes ready. When that happens it will take all the -necessary actions to deliver the result to the invoker of the script, -and then destroy itself. Should comm have lost the connection to the -invoker while the result is being computed the future will not try to -deliver the result it got, but just destroy itself. The future can be -configured with a command to call when the invoker is lost. This -enables the user to implement an early abort of the long-running -operation, should this be supported by it.

An example:

-# Procedure invoked by remote clients to run database operations.
-proc select {sql} {
-    # Signal the async generation of the result
-    set future [::comm::comm return_async]
-    # Generate an async db operation and tell it where to deliver the result.
-    set query [db query -command [list $future return] $sql]
-    # Tell the database system which query to cancel if the connection
-    # goes away while it is running.
-    $future configure -command [list db cancel $query]
-    # Note: The above will work without problem only if the async
-    # query will nover run its completion callback immediately, but
-    # only from the eventloop. Because otherwise the future we wish to
-    # configure may already be gone. If that is possible use 'catch'
-    # to prevent the error from propagating.
-    return
-}
-

The API of a future object is:

$future return ?-code code? ?value?

Use this method to tell the future that long-running operation has -completed. Arguments are an optional return value (defaults to the -empty string), and the Tcl return code (defaults to OK).

The future will deliver this information to invoker, if the connection -was not lost in the meantime, and then destroy itself. If the -connection was lost it will do nothing but destroy itself.

$future configure ?-command ?cmdprefix??

$future cget -command

These methods allow the user to retrieve and set a command to be -called if the connection the future belongs to has been lost.

Compatibility

comm exports itself as a package. The package version number -is in the form major . minor, where the major version will -only change when a non-compatible change happens to the API or -protocol. Minor bug fixes and changes will only affect the minor -version. To load comm this command is usually used:

-    package require comm 3
-

Note that requiring no version (or a specific version) can also be done.

The revision history of comm includes these releases:

4.6.3

Fixed ticket [ced0d60fc9]. Added proper detection of eof on a -socket, properly closing it.

4.6.2

Fixed bugs 2972571 and 3066872, the first a misdetection of quoted -brace after double backslash, the other a blocking gets making for an -obvious (hinsight) DoS attack on comm channels.

4.6.1

Changed the implementation of comm::commCollect to emulate -lindex's pre-Tcl 8 behaviour, i.e. it was given the ability to parse -out the first word of a list, even if the whole buffer is not a -well-formed list. Without this change the first word could only be -extracted if the whole buffer was a well-formed list (ever since Tcl -8), and in a ver-high-load situation, i.e. a server sending lots -and/or large commands very fast, this may never happen, eventually -crashing the receiver when it runs out of memory. With the change the -receiver is always able to process the first word when it becomes -well-formed, regardless of the structure of the remainder of the -buffer.

4.6

Added the option -socketcmd enabling users to override how a -socket is opened. The envisioned main use is the specification of the -tls::socket command, see package tls, to secure the -communication.

4.5.7

Changed handling of ports already in use to provide a proper error -message.

4.5.6

Bugfix in the replacement for vwait, made robust against of -variable names containing spaces.

4.5.5

Bugfix in the handling of hooks, typo in variable name.

4.5.4

Bugfix in the handling of the result received by the send -method. Replaced an after idle unset result with an immediate -unset, with the information saved to a local variable.

The after idle can spill into a forked child process if there -is no event loop between its setup and the fork. This may bork the -child if the next event loop is the vwait of comm's -send a few lines above the after idle, and the child -used the same serial number for its next request. In that case the -parent's after idle unset will delete the very array element -the child is waiting for, unlocking the vwait, causing it to -access a now missing array element, instead of the expected result.

4.5.3

Bugfixes in the wrappers for the builtin update and vwait -commands.

4.5.2

Bugfix in the wrapper for the builtin update command.

4.5.1

Bugfixes in the handling of -interp for regular scripts. The handling -of the buffer was wrong for scripts which are a single statement as -list. Fixed missing argument to new command commSendReply, -introduced by version 4.5. Affected debugging.

4.5

New server-side feature. The command invoked on the server can now -switch comm from the standard synchronous return of its result to an -asynchronous (defered) return. Due to the use of snit to implement the -future objects used by this feature from this version on comm -requires at least Tcl 8.3 to run. Please read the section -Asynchronous Result Generation for more details.

4.4.1

Bugfix in the execution of hooks.

4.4

Bugfixes in the handling of -interp for regular and hook -scripts. Bugfixes in channel cleanup.

4.3.1

Introduced -interp and -events to enable easy use of a slave interp -for execution of received scripts, and of event scripts.

4.3

Bugfixes, and introduces -silent to allow the user to force the -server/listening side to silently ignore connection attempts where the -protocol negotiation failed.

4.2

Bugfixes, and most important, switched to utf-8 as default encoding -for full i18n without any problems.

4.1

Rewrite of internal code to remove old pseudo-object model. Addition -of send -command asynchronous callback option.

4.0

Per request by John LoVerso. Improved handling of error for async -invoked commands.

3.7

Moved into tcllib and placed in a proper namespace.

3.6

A bug in the looking up of the remoteid for a executed command could -be triggered when the connection was closed while several asynchronous -sends were queued to be executed.

3.5

Internal change to how reply messages from a send are handled. -Reply messages are now decoded into the value to pass to -return; a new return statement is then cons'd up to with this -value. Previously, the return code was passed in from the remote as a -command to evaluate. Since the wire protocol has not changed, this is -still the case. Instead, the reply handling code decodes the -reply message.

3.4

Added more source commentary, as well as documenting config variables -in this man page. Fixed bug were loss of connection would give error -about a variable named pending rather than the message about -the lost connection. comm ids is now an alias for -comm interps (previously, it an alias for comm chans). -Since the method invocation change of 3.0, break and other exceptional -conditions were not being returned correctly from comm send. -This has been fixed by removing the extra level of indirection into -the internal procedure commSend. Also added propagation of -the errorCode variable. This means that these commands return -exactly as they would with send:

-    comm send id break
-    catch {comm send id break}
-    comm send id expr 1 / 0
-

Added a new hook for reply messages. Reworked method invocation to -avoid the use of comm:* procedures; this also cut the invocation time -down by 40%. Documented comm config (as this manual page -still listed the defunct comm init!)

3.3

Some minor bugs were corrected and the documentation was cleaned up. -Added some examples for hooks. The return semantics of the eval -hook were changed.

3.2

A new wire protocol, version 3, was added. This is backwards -compatible with version 2 but adds an exchange of supported protocol -versions to allow protocol negotiation in the future. Several bugs -with the hook implementation were fixed. A new section of the man -page on blocking semantics was added.

3.1

All the documented hooks were implemented. commLostHook was -removed. A bug in comm new was fixed.

3.0

This is a new version of comm with several major changes. -There is a new way of creating the methods available under the -comm command. The comm init method has been retired -and is replaced by comm configure which allows access to many -of the well-defined internal variables. This also generalizes the -options available to comm new. Finally, there is now a -protocol version exchanged when a connection is established. This -will allow for future on-wire protocol changes. Currently, the -protocol version is set to 2.

2.3

comm ids was renamed to comm channels. General -support for comm hook was fully implemented, but only the -lost hook exists, and it was changed to follow the general -hook API. commLostHook was unsupported (replaced by -comm hook lost) and commLost was removed.

2.2

The died hook was renamed lost, to be accessed by -commLostHook and an early implementation of -comm lost hook. As such, commDied is now -commLost.

2.1

Unsupported method comm remoteid was added.

2.0

comm has been rewritten from scratch (but is fully compatible -with Comm 1.0, without the requirement to use obTcl).

TLS Security Considerations

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

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

Author

John LoVerso, John@LoVerso.Southborough.MA.US

http://www.opengroup.org/~loverso/tcl-tk/#comm

License

Please see the file comm.LICENSE that accompanied this source, -or -http://www.opengroup.org/www/dist_client/caubweb/COPYRIGHT.free.html.

This license for comm, new as of version 3.2, allows it to be -used for free, without any licensing fee or royalty.

Bugs

If there is a failure initializing a channel created with -::comm::comm new, then the channel should be destroyed. -Currently, it is left in an inconsistent state.
There should be a way to force a channel to quiesce when changing the -configuration.

The following items can be implemented with the existing hooks and are -listed here as a reminder to provide a sample hook in a future -version.

Allow easier use of a slave interp for actual command execution -(especially when operating in "not local" mode).
Add host list (xhost-like) or "magic cookie" (xauth-like) -authentication to initial handshake.

The following are outstanding todo items.

Add an interp discovery and name->port mapping. This is likely to be -in a separate, optional nameserver. (See also the related work, -below.)
Fix the {id host} form so as not to be dependent upon -canonical hostnames. This requires fixes to Tcl to resolve hostnames!

This man page is bigger than the source file.

On Using Old Versions Of Tcl

Tcl7.5 under Windows contains a bug that causes the interpreter to -hang when EOF is reached on non-blocking sockets. This can be -triggered with a command such as this:

-    "comm send $other exit"
-

Always make sure the channel is quiescent before closing/exiting or -use at least Tcl7.6 under Windows.

Tcl7.6 on the Mac contains several bugs. It is recommended you use -at least Tcl7.6p2.

Tcl8.0 on UNIX contains a socket bug that can crash Tcl. It is recommended -you use Tcl8.0p1 (or Tcl7.6p2).

Related Work

Tcl-DP provides an RPC-based remote execution interface, but is a -compiled Tcl extension. See -http://www.cs.cornell.edu/Info/Projects/zeno/Projects/Tcl-DP.html.

Michael Doyle <miked@eolas.com> has code that implements the Tcl-DP -RPC interface using standard Tcl sockets, much like comm. -The DpTcl package is available at -http://chiselapp.com/user/gwlester/repository/DpTcl.

Andreas Kupries <andreas_kupries@users.sourceforge.net> uses -comm and has built a simple nameserver as part of his Pool -library. See http://www.purl.org/net/akupries/soft/pool/index.htm.

Bugs, Ideas, Feedback

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

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

Keywords

comm, communication, ipc, message, remote communication, remote execution, rpc, secure, send, socket, ssl, tls

Category

Programming tools

Copyright

DELETED embedded/www/tcllib/files/modules/comm/comm_wire.html Index: embedded/www/tcllib/files/modules/comm/comm_wire.html ================================================================== --- embedded/www/tcllib/files/modules/comm/comm_wire.html +++ /dev/null @@ -1,280 +0,0 @@ -

- -

comm_wire(n) 3 tcllib "Remote communication"

Name

comm_wire - The comm wire protocol

Table Of Contents
Synopsis
Description
Wire Protocol Version 3 -
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require comm

Description

This document contains a specification of the various versions of the -wire protocol used by comm internally for the communication between -its endpoints. It has no relevance to users of comm, only to -developers who wish to modify the package, write a compatible facility -in a different language, or some other facility based on the same -protocol.

Wire Protocol Version 3

Basic Layer

The basic encoding for all data is UTF-8. Because of this -binary data, including the NULL character, can be sent over the wire -as is, without the need for armoring it.

Basic Message Layer

On top of the Basic Layer we have a -message oriented exchange of data. -The totality of all characters written to the channel is a Tcl list, -with each element a separate message, each itself a list. The -messages in the overall list are separated by EOL. Note that EOL -characters can occur within the list as well. They can be -distinguished from the message-separating EOL by the fact that the -data from the beginning up to their location is not a valid Tcl list.

EOL is signaled through the linefeed character, i.e LF, or, -hex 0x0a. This is following the unix convention for -line-endings.

As a list each message is composed of words. Their meaning -depends on when the message was sent in the overall exchange. This is -described in the upcoming sections.

Negotiation Messages - Initial Handshake

The command protocol is defined like this:

The first message send by a client to a server, when opening the -connection, contains two words. The first word is a list as well, and -contains the versions of the wire protocol the client is willing to -accept, with the most preferred version first. The second word is the -TCP port the client is listening on for connections to itself. The -value 0 is used here to signal that the client will not listen -for connections, i.e. that it is purely for sending commands, and not -receiving them.
The first message sent by the server to the client, in response to the -message above contains only one word. This word is a list, containing -the string vers as its first element, and the version of the -wire protocol the server has selected from the offered versions as the -second.

Script/Command Messages

All messages coming after the initial handshake -consist of three words. These are an instruction, a transaction id, -and the payload. The valid instructions are shown below. The -transaction ids are used by the client to match any incoming replies -to the command messages it sent. This means that a server has to copy -the transaction id from a command message to the reply it sends for -that message.

send

async

command

The payload is the Tcl script to execute on the server. It is actually -a list containing the script fragments. These fragment are -concatenated together by the server to form the full script to -execute on the server side. -This emulates the Tcl "eval" semantics. -In most cases it is best to have only one word in the list, a list -containing the exact command.

Examples:

-    (a)     {send 1 {{array get tcl_platform}}}
-    (b)     {send 1 {array get tcl_platform}}
-    (c)     {send 1 {array {get tcl_platform}}}
-    are all valid representations of the same command. They are
-    generated via
-    (a')    send {array get tcl_platform}
-    (b')    send array get tcl_platform
-    (c')    send array {get tcl_platform}
-    respectively
-

Note that (a), generated by (a'), is the usual form, if only single -commands are sent by the client. -For example constructed using list, if the command contains -variable arguments. Like

-    send [list array get $the_variable]
-

These three instructions all invoke the script on the server -side. Their difference is in the treatment of result values, and thus -determines if a reply is expected.

send: A reply is expected. The sender is waiting for the result.
async: No reply is expected, the sender has no interest in the result and is -not waiting for any.
command: A reply is expected, but the sender is not waiting for it. It has -arranged to get a process-internal notification when the result -arrives.

reply

Like the previous three command, however the tcl script in the payload -is highly restricted. -It has to be a syntactically valid Tcl return command. This -contains result code, value, error code, and error info.

Examples:

-    {reply 1 {return -code 0 {}}}
-    {reply 1 {return -code 0 {osVersion 2.4.21-99-default byteOrder littleEndian machine i686 platform unix os Linux user andreask wordSize 4}}}
-

Bugs, Ideas, Feedback

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

Keywords

comm, communication, ipc, message, remote communication, remote execution, rpc, socket

Category

Programming tools

Copyright

DELETED embedded/www/tcllib/files/modules/control/control.html Index: embedded/www/tcllib/files/modules/control/control.html ================================================================== --- embedded/www/tcllib/files/modules/control/control.html +++ /dev/null @@ -1,258 +0,0 @@ -

- -

control(n) 0.1.3 tcllib "Tcl Control Flow Commands"

Name

control - Procedures for control flow structures.

Table Of Contents
Synopsis
Description
COMMANDS
LIMITATIONS
Bugs, Ideas, Feedback
See Also
Keywords
Category

Synopsis

package require Tcl 8.2
package require control ?0.1.3?

control::control command option ?arg arg ...?
control::assert expr ?arg arg ...?
control::do body ?option test?
control::no-op ?arg arg ...?

Description

The control package provides a variety of commands that provide -additional flow of control structures beyond the built-in ones -provided by Tcl. These are commands that in many programming -languages might be considered keywords, or a part of the -language itself. In Tcl, control flow structures are just commands -like everything else.

COMMANDS

control::control command option ?arg arg ...?

The control command is used as a configuration command for -customizing the other public commands of the control package. The -command argument names the command to be customized. The set of -valid option and subsequent arguments are determined by the -command being customized, and are documented with the command.

control::assert expr ?arg arg ...?

When disabled, the assert command behaves exactly like the -no-op command.

When enabled, the assert command evaluates expr as an -expression (in the same way that expr evaluates its argument). -If evaluation reveals that expr is not a valid boolean -expression (according to [string is boolean -strict]), -an error is raised. If expr evaluates to a true boolean value -(as recognized by if), then assert returns an empty -string. Otherwise, the remaining arguments to assert are used -to construct a message string. If there are no arguments, the message -string is "assertion failed: $expr". If there are arguments, they are -joined by join to form the message string. The message string -is then appended as an argument to a callback command, and the -completed callback command is evaluated in the global namespace.

The assert command can be customized by the control -command in two ways:

[control::control assert enabled ?boolean?] -queries or sets whether control::assert is enabled. When called -without a boolean argument, a boolean value is returned -indicating whether the control::assert command is enabled. When -called with a valid boolean value as the boolean argument, the -control::assert command is enabled or disabled to match the -argument, and an empty string is returned.

[control::control assert callback ?command?] -queries or sets the callback command that will be called by an enabled -assert on assertion failure. When called without a -command argument, the current callback command is returned. -When called with a command argument, that argument becomes the -new assertion failure callback command. Note that an assertion -failure callback command is always defined, even when assert -is disabled. The default callback command is -[return -code error].

Note that control::assert has been written so that in -combination with [namespace import], it is possible to -use enabled assert commands in some namespaces and disabled -assert commands in other namespaces at the same time. This -capability is useful so that debugging efforts can be independently -controlled module by module.

-% package require control
-% control::control assert enabled 1
-% namespace eval one namespace import ::control::assert
-% control::control assert enabled 0
-% namespace eval two namespace import ::control::assert
-% one::assert {1 == 0}
-assertion failed: 1 == 0
-% two::assert {1 == 0}
-

control::do body ?option test?

The do command evaluates the script body repeatedly -until the expression test becomes true or as long as -(while) test is true, depending on the value of -option being until or while. If -option and test are omitted the body is evaluated exactly -once. After normal completion, do returns an empty string. -Exceptional return codes (break, continue, error, -etc.) during the evaluation of body are handled in the same way -the while command handles them, except as noted in -LIMITATIONS, below.

control::no-op ?arg arg ...?

The no-op command takes any number of arguments and does -nothing. It returns an empty string.

LIMITATIONS

Several of the commands provided by the control package accept -arguments that are scripts to be evaluated. Due to fundamental -limitations of Tcl's catch and return commands, it is not -possible for these commands to properly evaluate the command -[return -code $code] within one of those script -arguments for any value of $code other than ok. In this -way, the commands of the control package are limited as compared -to Tcl's built-in control flow commands (such as if, -while, etc.) and those control flow commands that can be -provided by packages coded in C. An example of this difference:

-% package require control
-% proc a {} {while 1 {return -code error a}}
-% proc b {} {control::do {return -code error b} while 1}
-% catch a
-1
-% catch b
-0
-

Bugs, Ideas, Feedback

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

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

Keywords

assert, control, do, flow, no-op, structure

Category

Programming tools

DELETED embedded/www/tcllib/files/modules/coroutine/coro_auto.html Index: embedded/www/tcllib/files/modules/coroutine/coro_auto.html ================================================================== --- embedded/www/tcllib/files/modules/coroutine/coro_auto.html +++ /dev/null @@ -1,174 +0,0 @@ - -

- -

coroutine::auto(n) 1.1.3 tcllib "Coroutine utilities"

Name

coroutine::auto - Automatic event and IO coroutine awareness

Table Of Contents
Synopsis
Description
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.6
package require coroutine::auto 1.1.3
package require coroutine 1.1

Description

The coroutine::auto package provides no commands or other -directly visible functionality. -Built on top of the package coroutine, it intercepts various -builtin commands of the Tcl core to make any code using them -coroutine-oblivious, i.e. able to run inside and outside of a -coroutine without changes.

The commands so affected by this package are

after
exit
gets
global
read
update
vwait

Bugs, Ideas, Feedback

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

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

Keywords

after, channel, coroutine, events, exit, gets, global, green threads, read, threads, update, vwait

Category

Coroutine

Copyright

DELETED embedded/www/tcllib/files/modules/coroutine/tcllib_coroutine.html Index: embedded/www/tcllib/files/modules/coroutine/tcllib_coroutine.html ================================================================== --- embedded/www/tcllib/files/modules/coroutine/tcllib_coroutine.html +++ /dev/null @@ -1,225 +0,0 @@ - -

- -

coroutine(n) 1.2 tcllib "Coroutine utilities"

Name

coroutine - Coroutine based event and IO handling

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.6
package require coroutine 1.2

coroutine::util after delay
coroutine::util await varname...
coroutine::util create arg...
coroutine::util exit ?status?
coroutine::util gets chan ?varname?
coroutine::util gets_safety chan limit varname
coroutine::util global varname...
coroutine::util read -nonewline chan ?n?
coroutine::util update ?idletasks?
coroutine::util vwait varname

Description

The coroutine package provides coroutine-aware -implementations of various event- and channel related commands. It can -be in multiple modes:

Call the commands through their ensemble, in code which is -explicitly written for use within coroutines.
Import the commands into a namespace, either directly, or -through namespace path. This allows the use from within code -which is not coroutine-aware per se and restricted to specific -namespaces.

A more agressive form of making code coroutine-oblivious than point 2 -above is available through the package coroutine::auto, -which intercepts the relevant builtin commands and changes their -implementation dependending on the context they are run in, i.e. -inside or outside of a coroutine.

API

All the commands listed below are synchronous with respect to the -coroutine invoking them, i.e. this coroutine blocks until the result -is available. The overall eventloop is not blocked however.

coroutine::util after delay: This command delays the coroutine invoking it by delay -milliseconds.
coroutine::util await varname...: This command is an extension form of the coroutine::util vwait -command (see below) which waits on a write to one of many named -namespace variables.
coroutine::util create arg...: This command creates a new coroutine with an automatically assigned -name and causes it to run the code specified by the arguments.
coroutine::util exit ?status?: This command exits the current coroutine, causing it to return -status. If no status was specified the default 0 is -returned.
coroutine::util gets chan ?varname?: This command reads a line from the channel chan and returns it -either as its result, or, if a varname was specified, writes it -to the named variable and returns the number of characters read.
coroutine::util gets_safety chan limit varname: This command reads a line from the channel chan up to size limit -and stores the result in varname. Of limit is reached before the -set first newline, an error is thrown. The command returns the number of -characters read.
coroutine::util global varname...: This command imports the named global variables of the coroutine into -the current scope. From the technical point of view these variables -reside in level #1 of the Tcl stack. I.e. these are not the -regular global variable in to the global namespace, and each coroutine -can have their own set, independent of all others.
coroutine::util read -nonewline chan ?n?: This command reads n characters from the channel chan and -returns them as its result. If n is not specified the command -will read the channel until EOF is reached.
coroutine::util update ?idletasks?: This command causes the coroutine invoking it to run pending events or -idle handlers before proceeding.
coroutine::util vwait varname: This command causes the coroutine calling it to wait for a write to -the named namespace variable varname.

Bugs, Ideas, Feedback

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

Keywords

after, channel, coroutine, events, exit, gets, global, green threads, read, threads, update, vwait

Category

Coroutine

Copyright

DELETED embedded/www/tcllib/files/modules/counter/counter.html Index: embedded/www/tcllib/files/modules/counter/counter.html ================================================================== --- embedded/www/tcllib/files/modules/counter/counter.html +++ /dev/null @@ -1,299 +0,0 @@ - -

- -

counter(n) 2.0.4 tcllib "Counters and Histograms"

Name

counter - Procedures for counters and histograms

Table Of Contents
Synopsis
Description
Bugs, Ideas, Feedback
Keywords
Category

Synopsis

package require Tcl 8
package require counter ?2.0.4?

::counter::init tag args
::counter::count tag ?delta? ?instance?
::counter::start tag instance
::counter::stop tag instance
::counter::get tag args
::counter::exists tag
::counter::names
::counter::histHtmlDisplay tag args
::counter::reset tag args

Description

The counter package provides a counter facility and can -compute statistics and histograms over the collected data.

::counter::init tag args

This defines a counter with the name tag. The args -determines the characteristics of the counter. The args are

-group name: Keep a grouped counter where the name of the histogram bucket is -passed into ::counter::count.
-hist bucketsize: Accumulate the counter into histogram buckets of size -bucketsize. For example, if the samples are millisecond time -values and bucketsize is 10, then each histogram bucket -represents time values of 0 to 10 msec, 10 to 20 msec, 20 to 30 msec, -and so on.
-hist2x bucketsize: Accumulate the statistic into histogram buckets. The size of the -first bucket is bucketsize, each other bucket holds values 2 -times the size of the previous bucket. For example, if -bucketsize is 10, then each histogram bucket represents time -values of 0 to 10 msec, 10 to 20 msec, 20 to 40 msec, 40 to 80 msec, -and so on.
-hist10x bucketsize: Accumulate the statistic into histogram buckets. The size of the -first bucket is bucketsize, each other bucket holds values 10 -times the size of the previous bucket. For example, if -bucketsize is 10, then each histogram bucket represents time -values of 0 to 10 msec, 10 to 100 msec, 100 to 1000 msec, and so on.
-lastn N: Save the last N values of the counter to maintain a "running -average" over the last N values.
-timehist secsPerMinute: Keep a time-based histogram. The counter is summed into a histogram -bucket based on the current time. There are 60 per-minute buckets -that have a size determined by secsPerMinute, which is normally -60, but for testing purposes can be less. Every "hour" (i.e., 60 -"minutes") the contents of the per-minute buckets are summed into the -next hourly bucket. Every 24 "hours" the contents of the per-hour -buckets are summed into the next daily bucket. The counter package -keeps all time-based histograms in sync, so the first -secsPerMinute value seen by the package is used for all -subsequent time-based histograms.

::counter::count tag ?delta? ?instance?

Increment the counter identified by tag. The default increment -is 1, although you can increment by any value, integer or real, by -specifying delta. You must declare each counter with -::counter::init to define the characteristics of counter before -you start to use it. If the counter type is -group, then the -counter identified by instance is incremented.

::counter::start tag instance

Record the starting time of an interval. The tag is the name of -the counter defined as a -hist value-based histogram. The -instance is used to distinguish this interval from any other -intervals that might be overlapping this one.

::counter::stop tag instance

Record the ending time of an interval. The delta time since the -corresponding ::counter::start call for instance is -recorded in the histogram identified by tag.

::counter::get tag args

Return statistics about a counter identified by tag. The -args determine what value to return:

-total: Return the total value of the counter. This is the default if -args is not specified.
-totalVar: Return the name of the total variable. Useful for specifying with --textvariable in a Tk widget.
-N: Return the number of samples accumulated into the counter.
-avg: Return the average of samples accumulated into the counter.
-avgn: Return the average over the last N samples taken. The N -value is set in the ::counter::init call.
-hist bucket: If bucket is specified, then the value in that bucket of the -histogram is returned. Otherwise the complete histogram is returned -in array get format sorted by bucket.
-histVar: Return the name of the histogram array variable.
-histHour: Return the complete hourly histogram in array get format sorted by -bucket.
-histHourVar: Return the name of the hourly histogram array variable.
-histDay: Return the complete daily histogram in array get format sorted by -bucket.
-histDayVar: Return the name of the daily histogram array variable.
-resetDate: Return the clock seconds value recorded when the -counter was last reset.
-all: Return an array get of the array used to store the counter. This -includes the total, the number of samples (N), and any type-specific -information. This does not include the histogram array.

::counter::exists tag

Returns 1 if the counter is defined.

::counter::names

Returns a list of all counters defined.

::counter::histHtmlDisplay tag args

Generate HTML to display a histogram for a counter. The args -control the format of the display. They are:

-title string: Label to display above bar chart
-unit unit: Specify minutes, hours, or days for the -time-base histograms. For value-based histograms, the unit is -used in the title.
-images url: URL of /images directory.
-gif filename: Image for normal histogram bars. The filename is relative to -the -images directory.
-ongif filename: Image for the active histogram bar. The filename is relative to -the -images directory.
-max N: Maximum number of value-based buckets to display.
-height N: Pixel height of the highest bar.
-width N: Pixel width of each bar.
-skip N: Buckets to skip when labeling value-based histograms.
-format string: Format used to display labels of buckets.
-text boolean: If 1, a text version of the histogram is dumped, otherwise a graphical -one is generated.

::counter::reset tag args

Resets the counter with the name tag to an initial state. The -args determine the new characteristics of the counter. They have -the same meaning as described for ::counter::init.

Bugs, Ideas, Feedback

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

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

Keywords

counting, histogram, statistics, tallying

Category

Data structures

DELETED embedded/www/tcllib/files/modules/crc/cksum.html Index: embedded/www/tcllib/files/modules/crc/cksum.html ================================================================== --- embedded/www/tcllib/files/modules/crc/cksum.html +++ /dev/null @@ -1,239 +0,0 @@ - -

- -

cksum(n) 1.1.4 tcllib "Cyclic Redundancy Checks"

Name

cksum - Calculate a cksum(1) compatible checksum

Table Of Contents
Synopsis
Description
COMMANDS
OPTIONS
PROGRAMMING INTERFACE
EXAMPLES
AUTHORS
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require cksum ?1.1.4?

::crc::cksum ?-format format? ?-chunksize size? [ -channel chan | -filename file | string ]
::crc::CksumInit
::crc::CksumUpdate token data
::crc::CksumFinal token

Description

This package provides a Tcl implementation of the cksum(1) algorithm -based upon information provided at in the GNU implementation of this -program as part of the GNU Textutils 2.0 package.

COMMANDS

::crc::cksum ?-format format? ?-chunksize size? [ -channel chan | -filename file | string ]: The command takes string data or a channel or file name and returns a -checksum value calculated using the cksum(1) algorithm. The -result is formatted using the format(n) specifier provided or as -an unsigned integer (%u) by default.

OPTIONS

-channel name: Return a checksum for the data read from a channel. The command will -read data from the channel until the eof is true. If you need -to be able to process events during this calculation see the -PROGRAMMING INTERFACE section
-filename name: This is a convenience option that opens the specified file, sets the -encoding to binary and then acts as if the -channel option had -been used. The file is closed on completion.
-format string: Return the checksum using an alternative format template.

PROGRAMMING INTERFACE

The cksum package implements the checksum using a context variable to -which additional data can be added at any time. This is expecially -useful in an event based environment such as a Tk application or a web -server package. Data to be checksummed may be handled incrementally -during a fileevent handler in discrete chunks. This can improve -the interactive nature of a GUI application and can help to avoid -excessive memory consumption.

::crc::CksumInit: Begins a new cksum context. Returns a token ID that must be used for the -remaining functions. An optional seed may be specified if required.
::crc::CksumUpdate token data: Add data to the checksum identified by token. Calling -CksumUpdate $token "abcd" is equivalent to calling -CksumUpdate $token "ab" followed by -CksumUpdate $token "cb". See EXAMPLES.
::crc::CksumFinal token: Returns the checksum value and releases any resources held by this -token. Once this command completes the token will be invalid. The -result is a 32 bit integer value.

EXAMPLES

-% crc::cksum "Hello, World!"
-2609532967
-

-% crc::cksum -format 0x%X "Hello, World!"
-0x9B8A5027
-

-% crc::cksum -file cksum.tcl
-1828321145
-

-% set tok [crc::CksumInit]
-% crc::CksumUpdate $tok "Hello, "
-% crc::CksumUpdate $tok "World!"
-% crc::CksumFinal $tok
-2609532967
-

AUTHORS

Pat Thoyts

Bugs, Ideas, Feedback

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

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

Keywords

checksum, cksum, crc, crc32, cyclic redundancy check, data integrity, security

Category

Hashes, checksums, and encryption

Copyright

DELETED embedded/www/tcllib/files/modules/crc/crc16.html Index: embedded/www/tcllib/files/modules/crc/crc16.html ================================================================== --- embedded/www/tcllib/files/modules/crc/crc16.html +++ /dev/null @@ -1,255 +0,0 @@ - -

- -

crc16(n) 1.1.3 tcllib "Cyclic Redundancy Checks"

Name

crc16 - Perform a 16bit Cyclic Redundancy Check

Table Of Contents
Synopsis
Description
COMMANDS
OPTIONS
EXAMPLES
AUTHORS
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require crc16 ?1.1.3?

::crc::crc16 ?-format format? ?-seed value? ?-implementation procname? -- message
::crc::crc16 ?-format format? ?-seed value? ?-implementation procname? -filename file
::crc::crc-ccitt ?-format format? ?-seed value? ?-implementation procname? -- message
::crc::crc-ccitt ?-format format? ?-seed value? ?-implementation procname? -filename file
::crc::xmodem ?-format format? ?-seed value? ?-implementation procname? -- message
::crc::xmodem ?-format format? ?-seed value? ?-implementation procname? -filename file

Description

This package provides a Tcl-only implementation of the CRC -algorithms based upon information provided at -http://www.microconsultants.com/tips/crc/crc.txt -There are a number of permutations available for calculating CRC -checksums and this package can handle all of them. Defaults are set up -for the most common cases.

COMMANDS

::crc::crc16 ?-format format? ?-seed value? ?-implementation procname? -- message

::crc::crc16 ?-format format? ?-seed value? ?-implementation procname? -filename file

::crc::crc-ccitt ?-format format? ?-seed value? ?-implementation procname? -- message

::crc::crc-ccitt ?-format format? ?-seed value? ?-implementation procname? -filename file

::crc::xmodem ?-format format? ?-seed value? ?-implementation procname? -- message

::crc::xmodem ?-format format? ?-seed value? ?-implementation procname? -filename file

The command takes either string data or a file name and returns a checksum -value calculated using the CRC algorithm. The command used sets up the -CRC polynomial, initial value and bit ordering for the desired -standard checksum calculation. The result is formatted -using the format(n) specifier provided or as an unsigned integer -(%u) by default.

A number of common polynomials are in use with the CRC algorithm and -the most commonly used of these are included in this package. For -convenience each of these has a command alias in the crc namespace.

It is possible to implement the CRC-32 checksum using this crc16 -package as the implementation is sufficiently generic to extend to 32 -bit checksums. As an example this has been done already - however this -is not the fastest method to implement this algorithm in Tcl and a -separate crc32 package is available.

OPTIONS

-filename name

Return a checksum for the file contents instead of for parameter data.

-format string

Return the checksum using an alternative format template.

-seed value

Select an alternative seed value for the CRC calculation. The default -is 0 for the CRC16 calculation and 0xFFFF for the CCITT version. -This can be useful for calculating the CRC for data -structures without first converting the whole structure into a -string. The CRC of the previous member can be used as the seed for -calculating the CRC of the next member. It is also used for -accumulating a checksum from fragments of a large message (or file)

-implementation procname

This hook is provided to allow users to provide their own -implementation (perhaps a C compiled extension). The -procedure specfied is called with two parameters. The first is the -data to be checksummed and the second is the seed value. An -integer is expected as the result.

The package provides some implementations of standard CRC polynomials -for the XMODEM, CCITT and the usual CRC-16 checksum. For convenience, -additional commands have been provided that make use of these -implementations.

--

Terminate option processing. Please note that using the option -termination flag is important when processing data from parameters. If -the binary data looks like one of the options given above then the -data will be read as an option if this marker is not included. -Always use the -- option termination flag before giving the data -argument.

EXAMPLES

-% crc::crc16 -- "Hello, World!"
-64077
-

-% crc::crc-ccitt -- "Hello, World!"
-26586
-

-% crc::crc16 -format 0x%X -- "Hello, World!"
-0xFA4D
-

-% crc::crc16 -file crc16.tcl
-51675
-

AUTHORS

Pat Thoyts

Bugs, Ideas, Feedback

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

Keywords

checksum, cksum, crc, crc16, crc32, cyclic redundancy check, data integrity, security

Category

Hashes, checksums, and encryption

Copyright

DELETED embedded/www/tcllib/files/modules/crc/crc32.html Index: embedded/www/tcllib/files/modules/crc/crc32.html ================================================================== --- embedded/www/tcllib/files/modules/crc/crc32.html +++ /dev/null @@ -1,254 +0,0 @@ - -

- -

crc32(n) 1.3.2 tcllib "Cyclic Redundancy Checks"

Name

crc32 - Perform a 32bit Cyclic Redundancy Check

Table Of Contents
Synopsis
Description
COMMANDS
OPTIONS
PROGRAMMING INTERFACE
EXAMPLES
AUTHORS
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require crc32 ?1.3.2?

::crc::crc32 ?-format format? ?-seed value? [ -channel chan | -filename file | message ]
::crc::Crc32Init ?seed?
::crc::Crc32Update token data
::crc::Crc32Final token

Description

This package provides a Tcl implementation of the CRC-32 -algorithm based upon information provided at -http://www.naaccr.org/standard/crc32/document.html -If either the critcl package or the Trf package -are available then a compiled version may be used internally to -accelerate the checksum calculation.

COMMANDS

::crc::crc32 ?-format format? ?-seed value? [ -channel chan | -filename file | message ]: The command takes either string data or a channel or file name and -returns a checksum value calculated using the CRC-32 algorithm. The -result is formatted using the format(n) specifier provided. The -default is to return the value as an unsigned integer (format %u).

OPTIONS

-channel name: Return a checksum for the data read from a channel. The command will -read data from the channel until the eof is true. If you need -to be able to process events during this calculation see the -PROGRAMMING INTERFACE section
-filename name: This is a convenience option that opens the specified file, sets the -encoding to binary and then acts as if the -channel option had -been used. The file is closed on completion.
-format string: Return the checksum using an alternative format template.
-seed value: Select an alternative seed value for the CRC calculation. The default -is 0xffffffff. This can be useful for calculating the CRC for data -structures without first converting the whole structure into a -string. The CRC of the previous member can be used as the seed for -calculating the CRC of the next member. -Note that the crc32 algorithm includes a final XOR step. If -incremental processing is desired then this must be undone before -using the output of the algorithm as the seed for further -processing. A simpler alternative is to use the -PROGRAMMING INTERFACE which is intended for this mode of -operation.

PROGRAMMING INTERFACE

The CRC-32 package implements the checksum using a context variable to -which additional data can be added at any time. This is expecially -useful in an event based environment such as a Tk application or a web -server package. Data to be checksummed may be handled incrementally -during a fileevent handler in discrete chunks. This can improve -the interactive nature of a GUI application and can help to avoid -excessive memory consumption.

::crc::Crc32Init ?seed?: Begins a new CRC32 context. Returns a token ID that must be used for the -remaining functions. An optional seed may be specified if required.
::crc::Crc32Update token data: Add data to the checksum identified by token. Calling -Crc32Update $token "abcd" is equivalent to calling -Crc32Update $token "ab" followed by -Crc32Update $token "cb". See EXAMPLES.
::crc::Crc32Final token: Returns the checksum value and releases any resources held by this -token. Once this command completes the token will be invalid. The -result is a 32 bit integer value.

EXAMPLES

-% crc::crc32 "Hello, World!"
-3964322768
-

-% crc::crc32 -format 0x%X "Hello, World!"
-0xEC4AC3D0
-

-% crc::crc32 -file crc32.tcl
-483919716
-

-% set tok [crc::Crc32Init]
-% crc::Crc32Update $tok "Hello, "
-% crc::Crc32Update $tok "World!"
-% crc::Crc32Final $tok
-3964322768
-

AUTHORS

Pat Thoyts

Bugs, Ideas, Feedback

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

Keywords

checksum, cksum, crc, crc32, cyclic redundancy check, data integrity, security

Category

Hashes, checksums, and encryption

Copyright

DELETED embedded/www/tcllib/files/modules/crc/sum.html Index: embedded/www/tcllib/files/modules/crc/sum.html ================================================================== --- embedded/www/tcllib/files/modules/crc/sum.html +++ /dev/null @@ -1,214 +0,0 @@ - -

- -

sum(n) 1.1.2 tcllib "Cyclic Redundancy Checks"

Name

sum - Calculate a sum(1) compatible checksum

Table Of Contents
Synopsis
Description
COMMANDS
OPTIONS
EXAMPLES
AUTHORS
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require sum ?1.1.2?

::crc::sum ?-bsd | -sysv? ?-format fmt? ?-chunksize size? [ -filename file | -channel chan | string ]

Description

This package provides a Tcl-only implementation of the sum(1) command -which calculates a 16 bit checksum value from the input data. The BSD -sum algorithm is used by default but the SysV algorithm is also -available.

COMMANDS

::crc::sum ?-bsd | -sysv? ?-format fmt? ?-chunksize size? [ -filename file | -channel chan | string ]: The command takes string data or a file name or a channel and returns -a checksum value calculated using the sum(1) algorithm. The -result is formatted using the format(n) specifier provided or as -an unsigned integer (%u) by default.

OPTIONS

-sysv: The SysV algorithm is fairly naive. The byte values are summed and any -overflow is discarded. The lowest 16 bits are returned as the -checksum. Input with the same content but different ordering will -give the same result.
-bsd: This algorithm is similar to the SysV version but includes a bit rotation -step which provides a dependency on the order of the data values.
-filename name: Return a checksum for the file contents instead of for parameter data.
-channel chan: Return a checksum for the contents of the specified channel. The -channel must be open for reading and should be configured for binary -translation. The channel will no be closed on completion.
-chunksize size: Set the block size used when reading data from either files or -channels. This value defaults to 4096.
-format string: Return the checksum using an alternative format template.

EXAMPLES

-% crc::sum "Hello, World!"
-37287
-

-% crc::sum -format 0x%X "Hello, World!"
-0x91A7
-

-% crc::sum -file sum.tcl
-13392
-

AUTHORS

Pat Thoyts

Bugs, Ideas, Feedback

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

Keywords

checksum, cksum, crc, crc32, cyclic redundancy check, data integrity, security, sum

Category

Hashes, checksums, and encryption

Copyright

DELETED embedded/www/tcllib/files/modules/cron/cron.html Index: embedded/www/tcllib/files/modules/cron/cron.html ================================================================== --- embedded/www/tcllib/files/modules/cron/cron.html +++ /dev/null @@ -1,298 +0,0 @@ - -

- -

cron(n) 2.1 tcllib "cron"

Name

cron - Tool for automating the period callback of commands

Table Of Contents
Synopsis
Description
Commands
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.6
package require cron ?2.1?

::cron::at ?processname? timecode command
::cron::cancel processname
::cron::every processname frequency command
::cron::in ?processname? timecode command
::cron::object_coroutine object coroutine ?info?
::cron::sleep milliseconds
::cron::task delete process
::cron::task exists process
::cron::task info process
::cron::task set process field value ?field...? ?value...?
::cron::wake ?who?
::cron::clock_step milliseconds
::cron::clock_delay milliseconds
::cron::clock_sleep seconds ?offset?
::cron::clock_set newtime

Description

The cron package provides a Pure-tcl set of tools to allow -programs to schedule tasks to occur at regular intervals. Rather than -force each task to issue it's own call to the event loop, the cron -system mimics the cron utility in Unix: on task periodically checks to -see if something is to be done, and issues all commands for a given -time step at once.

Changes in version 2.0

While cron was originally designed to handle time scales > 1 second, the -latest version's internal understand time granularity down to the millisecond, -making it easier to integrate with other timed events. -Version 2.0 also understands how to properly integrate coroutines and objects. -It also adds a facility for an external (or script driven) clock. Note that vwait style events -won't work very well with an external clock.

Commands

::cron::at ?processname? timecode command

This command registers a command to be called at the time specified by timecode. -If timecode is expressed as an integer, the timecode is assumed to be in unixtime. All -other inputs will be interpreted by clock scan and converted to unix time. -This task can be modified by subsequent calls to -this package's commands by referencing processname. If processname exists, -it will be replaced. -If processname is not given, one is generated and returned by the command.

-::cron::at start_coffee {Tomorrow at 9:00am}  {remote::exec::coffeepot power on}
-::cron::at shutdown_coffee {Tomorrow at 12:00pm}  {remote::exec::coffeepot power off}
-

::cron::cancel processname

This command unregisters the process processname and cancels any pending commands. -Note: processname can be a process created by either ::cron::at or ::cron::every.

-::cron::cancel check_mail
-

::cron::every processname frequency command

This command registers a command to be called at the interval of frequency. -frequency is given in seconds. This task can be modified by subsequent calls to -this package's commands by referencing processname. If processname exists, -it will be replaced.

-::cron::every check_mail 900  ::imap_client::check_mail
-::cron::every backup_db  3600 {::backup_procedure ::mydb}
-

::cron::in ?processname? timecode command

This command registers a command to be called after a delay of time specified by timecode. -timecode is expressed as an seconds. -This task can be modified by subsequent calls to -this package's commands by referencing processname. If processname exists, -it will be replaced. -If processname is not given, one is generated and returned by the command.

::cron::object_coroutine object coroutine ?info?

This command registers a coroutine, associated with object to be called -given the parameters of info. If now parameters are given, the coroutine is assumed -to be an idle task which will self-terminate. info can be given in any form compadible with -::cron::task set

::cron::sleep milliseconds

When run within a coroutine, this command will register the coroutine for a callback -at the appointed time, and immediately yield.

If the ::cron::time variable is > 0 this command will advance the internal time, -100ms at a time.

In all other cases this command will generate a fictious variable, generate an -after call, and vwait the variable:

-set eventid [incr ::cron::eventcount]
-set var ::cron::event_#$eventid
-set $var 0
-::after $ms "set $var 1"
-::vwait $var
-::unset $var
-

Usage:

-::cron::sleep 250
-

::cron::task delete process

Delete the process specified the process

::cron::task exists process

Returns true if process is registered with cron.

::cron::task info process

Returns a dict describing process. See ::cron::task set for a description of the options.

::cron::task set process field value ?field...? ?value...?

If process does not exist, it is created. Options Include:

command: If coroutine is black, a global command which implements this process. If coroutine is not -black, the command to invoke to create or recreate the coroutine.
coroutine: The name of the coroutine (if any) which implements this process.
frequency: If -1, this process is terminated after the next event. If 0 this process should be called during every -idle event. If positive, this process should generate events periodically. The frequency is an integer number -of milliseconds between events.
object: The object associated with this process or coroutine.
scheduled: If non-zero, the absolute time from the epoch (in milliseconds) that this process will trigger an event. -If zero, and the frequency is also zero, this process is called every idle loop.
running: A boolean flag. If true it indicates the process never returned or yielded during the event loop, -and will not be called again until it does so.

::cron::wake ?who?

Wake up cron, and arrange for its event loop to be run during the next Idle cycle.

-::cron::wake {I just did something important}
-

Several utility commands are provided that are used internally within cron and for -testing cron, but may or may not be useful in the general cases.

::cron::clock_step milliseconds

Return a clock time absolute to the epoch which falls on the next -border between one second and the next for the value of milliseconds

::cron::clock_delay milliseconds

Return a clock time absolute to the epoch which falls on the next -border between one second and the next milliseconds in the future.

::cron::clock_sleep seconds ?offset?

Return a clock time absolute to the epoch which falls exactly seconds in -the future. If offset is given it may be positive or negative, and will shift -the final time to before or after the second would flip.

::cron::clock_set newtime

Sets the internal clock for cron. This command will advance the time in 100ms -increment, triggering events, until the internal time catches up with newtime.

newtime is expressed in absolute milliseconds since the beginning of the epoch.

Bugs, Ideas, Feedback

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

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

Keywords

cron, odie

Category

System

Copyright

DELETED embedded/www/tcllib/files/modules/csv/csv.html Index: embedded/www/tcllib/files/modules/csv/csv.html ================================================================== --- embedded/www/tcllib/files/modules/csv/csv.html +++ /dev/null @@ -1,319 +0,0 @@ - -

- -

csv(n) 0.8.1 tcllib "CSV processing"

Name

csv - Procedures to handle CSV data.

Table Of Contents
Synopsis
Description
COMMANDS
FORMAT
EXAMPLE
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require csv ?0.8.1?

::csv::iscomplete data
::csv::join values ?sepChar? ?delChar? ?delMode?
::csv::joinlist values ?sepChar? ?delChar? ?delMode?
::csv::joinmatrix matrix ?sepChar? ?delChar? ?delMode?
::csv::read2matrix ?-alternate? chan m {sepChar ,} {expand none}
::csv::read2queue ?-alternate? chan q {sepChar ,}
::csv::report cmd matrix ?chan?
::csv::split ?-alternate? line ?sepChar? ?delChar?
::csv::split2matrix ?-alternate? m line {sepChar ,} {expand none}
::csv::split2queue ?-alternate? q line {sepChar ,}
::csv::writematrix m chan ?sepChar? ?delChar?
::csv::writequeue q chan ?sepChar? ?delChar?

Description

The csv package provides commands to manipulate information -in CSV FORMAT (CSV = Comma Separated Values).

COMMANDS

The following commands are available:

::csv::iscomplete data

A predicate checking if the argument data is a complete csv -record. The result is a boolean flag indicating the completeness of -the data. The result is true if the data is complete.

::csv::join values ?sepChar? ?delChar? ?delMode?

Takes a list of values and returns a string in CSV format containing -these values. The separator character can be defined by the caller, -but this is optional. The default is ",". The quoting aka delimiting character can -be defined by the caller, but this is optional. The default is '"'. -By default the quoting mode delMode is "auto", surrounding -values with delChar only when needed. When set to "always" -however, values are always surrounded by the delChar instead.

::csv::joinlist values ?sepChar? ?delChar? ?delMode?

Takes a list of lists of values and returns a string in CSV format -containing these values. The separator character can be defined by the -caller, but this is optional. The default is ",". The quoting character -can be defined by the caller, but this is optional. The default is '"'. -By default the quoting mode delMode is "auto", surrounding -values with delChar only when needed. When set to "always" -however, values are always surrounded by the delChar instead. -Each element of the outer list is considered a record, these are -separated by newlines in the result. The elements of each record are -formatted as usual (via ::csv::join).

::csv::joinmatrix matrix ?sepChar? ?delChar? ?delMode?

Takes a matrix object following the API specified for the -struct::matrix package and returns a string in CSV format containing -these values. The separator character can be defined by the caller, -but this is optional. The default is ",". The quoting character -can be defined by the caller, but this is optional. The default is -'"'. -By default the quoting mode delMode is "auto", surrounding -values with delChar only when needed. When set to "always" -however, values are always surrounded by the delChar instead. -Each row of the matrix is considered a record, these are -separated by newlines in the result. The elements of each record are -formatted as usual (via ::csv::join).

::csv::read2matrix ?-alternate? chan m {sepChar ,} {expand none}

A wrapper around ::csv::split2matrix (see below) reading -CSV-formatted lines from the specified channel (until EOF) and adding -them to the given matrix. For an explanation of the expand -argument see ::csv::split2matrix.

::csv::read2queue ?-alternate? chan q {sepChar ,}

A wrapper around ::csv::split2queue (see below) reading -CSV-formatted lines from the specified channel (until EOF) and adding -them to the given queue.

::csv::report cmd matrix ?chan?

A report command which can be used by the matrix methods -format 2string and format 2chan. For the latter this -command delegates the work to ::csv::writematrix. cmd is -expected to be either printmatrix or -printmatrix2channel. The channel argument, chan, has -to be present for the latter and must not be present for the first.

::csv::split ?-alternate? line ?sepChar? ?delChar?

converts a line in CSV format into a list of the values -contained in the line. The character used to separate the values from -each other can be defined by the caller, via sepChar, but this -is optional. The default is ",". The quoting character can be defined -by the caller, but this is optional. The default is '"'.

If the option -alternate is specified a slightly different -syntax is used to parse the input. This syntax is explained below, in -the section FORMAT.

::csv::split2matrix ?-alternate? m line {sepChar ,} {expand none}

The same as ::csv::split, but appends the resulting list as a -new row to the matrix m, using the method add row. The -expansion mode specified via expand determines how the command -handles a matrix with less columns than contained in line. The -allowed modes are:

none: This is the default mode. In this mode it is the responsibility of the -caller to ensure that the matrix has enough columns to contain the -full line. If there are not enough columns the list of values is -silently truncated at the end to fit.
empty: In this mode the command expands an empty matrix to hold all columns -of the specified line, but goes no further. The overall effect is that -the first of a series of lines determines the number of columns in the -matrix and all following lines are truncated to that size, as if mode -none was set.
auto: In this mode the command expands the matrix as needed to hold all -columns contained in line. The overall effect is that after -adding a series of lines the matrix will have enough columns to hold -all columns of the longest line encountered so far.

::csv::split2queue ?-alternate? q line {sepChar ,}

The same as ::csv::split, but appending the resulting list as a -single item to the queue q, using the method put.

::csv::writematrix m chan ?sepChar? ?delChar?

A wrapper around ::csv::join taking all rows in the matrix -m and writing them CSV formatted into the channel chan.

::csv::writequeue q chan ?sepChar? ?delChar?

A wrapper around ::csv::join taking all items in the queue -q (assumes that they are lists) and writing them CSV formatted -into the channel chan.

FORMAT

The format of regular CSV files is specified as

Each record of a csv file (comma-separated values, as exported e.g. by -Excel) is a set of ASCII values separated by ",". For other languages -it may be ";" however, although this is not important for this case as -the functions provided here allow any separator character.
If and only if a value contains itself the separator ",", then it (the -value) has to be put between "". If the value does not contain the -separator character then quoting is optional.
If a value contains the character ", that character is represented by "".
The output string "" represents the value ". In other words, it is -assumed that it was created through rule 3, and only this rule, -i.e. that the value was not quoted.

An alternate format definition mainly used by MS products specifies -that the output string "" is a representation of the empty -string. In other words, it is assumed that the output was generated -out of the empty string by quoting it (i.e. rule 2), and not through -rule 3. This is the only difference between the regular and the -alternate format.

The alternate format is activated through specification of the option --alternate to the various split commands.

EXAMPLE

Using the regular format the record

-123,"123,521.2","Mary says ""Hello, I am Mary""",""
-

is parsed into the items

-a) 123
-b) 123,521.2
-c) Mary says "Hello, I am Mary"
-d) "
-

Using the alternate format the result is

-a) 123
-b) 123,521.2
-c) Mary says "Hello, I am Mary"
-d) (the empty string)
-

instead. As can be seen only item (d) is different, now the empty string -instead of a ".

Bugs, Ideas, Feedback

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

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

Keywords

csv, matrix, package, queue, tcllib

Category

Text processing

Copyright

DELETED embedded/www/tcllib/files/modules/debug/debug.html Index: embedded/www/tcllib/files/modules/debug/debug.html ================================================================== --- embedded/www/tcllib/files/modules/debug/debug.html +++ /dev/null @@ -1,306 +0,0 @@ - -

- -

debug(n) 1.0.6 tcllib "debug narrative"

Name

debug - debug narrative - core

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.5
package require debug ?1.0.6?

debug.tag message ?level?
debug 2array
debug define tag
debug header text
debug level tag ?level? ?fd?
debug names
debug off tag
debug on tag
debug parray arrayvarname
debug pdict dict
debug hexl data ?prefix?
debug nl
debug tab
debug prefix tag ?text?
debug setting (tag level) ... ?fd?
debug suffix tag ?text?
debug trailer text

Description

Debugging areas of interest are represented by 'tags' which have -independently settable levels of interest (an integer, higher is more -detailed).

API

debug.tag message ?level?

For each known tag the package creates a command with this signature -the user can then use to provide the debug narrative of the tag. -The narrative message is provided as a Tcl script whose value is -substed in the caller's scope if and only if the current level of -interest for the tag matches or exceeds the call's level -of detail. This is useful, as one can place arbitrarily complex -narrative in code without unnecessarily evaluating it.

See methods level and setting for querying -and manipulating the current level of detail for tags.

The actually printed text consists of not only the -message, but also global and tag-specific prefix and suffix, -should they exist, with each line in the message having the specified -headers and trailers.

All these parts are substableTcl scripts, which are -substituted once per message before assembly.

debug 2array

This method returns a dictionary mapping the names of all debug tags -currently known to the package to their state and log level. The -latter are encoded in a single numeric value, where a negative number -indicates an inactive tag at the level given by the absolute value, and -a positive number is an active tag at that level.

Bugs, Ideas, Feedback

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

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

Keywords

debug, log, narrative, trace

Category

debugging, tracing, and logging

Copyright

DELETED embedded/www/tcllib/files/modules/debug/debug_caller.html Index: embedded/www/tcllib/files/modules/debug/debug_caller.html ================================================================== --- embedded/www/tcllib/files/modules/debug/debug_caller.html +++ /dev/null @@ -1,172 +0,0 @@ - -

- -

debug::caller(n) 1.1 tcllib "debug narrative"

Name

debug::caller - debug narrative - caller

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.5
package require debug::caller ?1.1?

debug caller ?args...?

Description

API

debug caller ?args...?

This method is useful in a tag-specific prefix to automatically -provide caller information for all uses of the tag. Or in a message, -when only specific places need such detail.

Beyond that it recognizing the various internal forms of method -calls generated by the snit OO system and rewrites these to -their original form, for better readability. -Similarly for TclOO.

If args are specified then they are treated as the -integer indices of command arguments to not show in the -output. The referenced arguments are replaced by * instead. -The main anticipiated use case for this is the exclusion of arguments -expected to contain large Tcl values, i.e. long lists, large -dictionaries, etc. to prevent them from overwhelming the narrative.

Bugs, Ideas, Feedback

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

Keywords

debug, log, narrative, trace

Category

debugging, tracing, and logging

Copyright

DELETED embedded/www/tcllib/files/modules/debug/debug_heartbeat.html Index: embedded/www/tcllib/files/modules/debug/debug_heartbeat.html ================================================================== --- embedded/www/tcllib/files/modules/debug/debug_heartbeat.html +++ /dev/null @@ -1,170 +0,0 @@ - -

- -

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

Name

debug::heartbeat - debug narrative - heartbeat

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.5
package require debug::heartbeat ?1?
package require debug ?1?

debug heartbeat ?delta?

Description

API

debug heartbeat ?delta?

This method activates or disables a heartbeat with which to monitor -the event loop of an event-based Tcl application.

It reserves the debug tag heartbeat for its operation -and writes a message every delta milliseconds.

A delta-value <= 0 disables the heartbeat.

The message produced by the heartbeat contains a sequence -counter and the time in milliseconds since the last beat, thus -providing insight into timing variationsn and deviations from the -nominal delta.

Bugs, Ideas, Feedback

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

Keywords

debug, heartbeat, log, narrative, trace

Category

debugging, tracing, and logging

Copyright

DELETED embedded/www/tcllib/files/modules/debug/debug_timestamp.html Index: embedded/www/tcllib/files/modules/debug/debug_timestamp.html ================================================================== --- embedded/www/tcllib/files/modules/debug/debug_timestamp.html +++ /dev/null @@ -1,165 +0,0 @@ - -

- -

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

Name

debug::timestamp - debug narrative - timestamping

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.5
package require debug::timestamp ?1?
package require debug ?1?

debug timestamp

Description

API

debug timestamp: This method returns millisecond timing information since a baseline or -last call, making it useful in a tag-specific prefix to automatically -provide caller information for all uses of the tag. Or in a message, -when only specific places need such detail.

Bugs, Ideas, Feedback

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

Keywords

debug, log, narrative, timestamps, trace

Category

debugging, tracing, and logging

Copyright

DELETED embedded/www/tcllib/files/modules/defer/defer.html Index: embedded/www/tcllib/files/modules/defer/defer.html ================================================================== --- embedded/www/tcllib/files/modules/defer/defer.html +++ /dev/null @@ -1,217 +0,0 @@ - -

- -

defer(n) 1 tcllib "Defered execution ala Go"

Name

defer - Defered execution

Table Of Contents
Synopsis
Description
COMMANDS
EXAMPLES
REFERENCES
AUTHORS
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.6
package require defer ?1?

::defer::defer ?command? ?arg1? ?arg2? ?argN...?
::defer::with variableList script
::defer::autowith script
::defer::cancel ?id...?

Description

The defer commands allow a developer to schedule actions to happen -as part of the current variable scope terminating. This is most useful -for dealing with cleanup activities. Since the defered actions always -execute, and always execute in the reverse order from which the defer -statements themselves execute, the programmer can schedule the cleanup -of a resource (for example, a channel) as soon as that resource is -acquired. Then, later if the procedure or lambda ends, either due to -an error, or an explicit return, the cleanup of that resource will -always occur.

COMMANDS

::defer::defer ?command? ?arg1? ?arg2? ?argN...?: Defers execution of some code until the current variable scope -ends. Each argument is concatencated together to form the script -to execute at deferal time. -Multiple defer statements may be used, they are executed in the order -of last-in, first-out. -The return value is an identifier which can be used later with -defer::cancel
::defer::with variableList script: Defers execution of a script while copying the current value of some -variables, whose names specified in variableList, into the script. -The script acts like a lambda but executes at the same level as the -defer::with -call. -The return value is the same as -::defer::defer
::defer::autowith script: The same as -::defer::with but uses all local variables in the variable list.
::defer::cancel ?id...?: Cancels the execution of a defered action. The id argument is the -identifier returned by -::defer::defer, -::defer::with, or -::defer::autowith. -Any number of arguments may be supplied, and all of the IDs supplied -will be cancelled.

EXAMPLES

-	package require defer 1
-	apply {{} {
-		set fd [open /dev/null]
-		defer::defer close $fd
-	}}
-

REFERENCES

AUTHORS

Roy Keene

Bugs, Ideas, Feedback

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

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

Keywords

cleanup, golang

Category

Utility

Copyright

DELETED embedded/www/tcllib/files/modules/des/des.html Index: embedded/www/tcllib/files/modules/des/des.html ================================================================== --- embedded/www/tcllib/files/modules/des/des.html +++ /dev/null @@ -1,292 +0,0 @@ - -

- -

des(n) 1.1 tcllib "Data Encryption Standard (DES)"

Name

des - Implementation of the DES and triple-DES ciphers

Table Of Contents
Synopsis
Description
COMMANDS
PROGRAMMING INTERFACE
MODES OF OPERATION
EXAMPLES
REFERENCES
AUTHORS
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require des 1.1

::DES::des ?-mode [ecb|cbc|cfb|ofb]? ?-dir [encrypt|decrypt]? -key keydata ?-iv vector? ?-hex? ?-weak? ?-out channel? ?-chunksize size? [ -in channel | data ]
::DES::Init mode keydata iv ?weak?
::DES::Encrypt Key data
::DES::Decrypt Key data
::DES::Reset Key iv
::DES::Final Key

Description

This is an implementation in Tcl of the Data Encryption Standard (DES) -as published by the U.S. National Institute of Standards and -Technology (NIST) [1]. This implementation also supports triple -DES (3DES) extension to DES. DES is a 64-bit block cipher that uses a -56-bit key. 3DES uses a 168-bit key. DES has now officially been -superceeded by AES but is in common use in many protocols.

The tcllib implementation of DES and 3DES uses an implementation by -Mac Cody and is available as a separate download from [2]. For -anyone concerned about the details of exporting this code please see -the TclDES web pages. The tcllib specific code is a wrapper to the -TclDES API that presents same API for the DES cipher as for other -ciphers in the library.

COMMANDS

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

The -key option must be given. This parameter takes a binary -string of 8 bytes in length and is used to generate the key schedule. -In DES only 56 bits of key data are used. The highest bit from each -byte is discarded.

The -mode and -dir options are optional and default to cbc -mode and encrypt respectively. The initialization vector -iv -takes an 8 byte binary argument. This defaults to all zeros. See -MODES OF OPERATION for more about -mode and the use -of the initialization vector.

DES is a 64-bit block cipher. This means that the data must be -provided in units that are a multiple of 8 bytes.

PROGRAMMING INTERFACE

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

::DES::Init mode keydata iv ?weak?

Construct a new DES key schedule using the specified key data and the -given initialization vector. The initialization vector is not used -with ECB mode but is important for other usage modes. -See MODES OF OPERATION.

There are a small number of keys that are known to be weak when used -with DES. By default if such a key is passed in then an error will be -raised. If there is a need to accept such keys then the weak -parameter can be set true to avoid the error being thrown.

::DES::Encrypt Key data

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

::DES::Decrypt Key data

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

::DES::Reset Key iv

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

::DES::Final Key

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

MODES OF OPERATION

Electronic Code Book (ECB): ECB is the basic mode of all block ciphers. Each block is encrypted -independently and so identical plain text will produce identical -output when encrypted with the same key. Any encryption errors will -only affect a single block however this is vulnerable to known -plaintext attacks.
Cipher Block Chaining (CBC): CBC mode uses the output of the last block encryption to affect the -current block. An initialization vector of the same size as the cipher -block size is used to handle the first block. The initialization -vector should be chosen randomly and transmitted as the first block of -the output. Errors in encryption affect the current block and the next -block after which the cipher will correct itself. CBC is the most -commonly used mode in software encryption.
Cipher Feedback (CFB): CFB mode can be used to convert block ciphers into stream ciphers. In -CFB mode the initialization vector is encrypted and the output is then -xor'd with the plaintext stream. The result is then used as the -initialization vector for the next round. Errors will affect the -current block and the next block.
Output Feedback (OFB): OFB is similar to CFB except that the output of the cipher is fed back -into the next round and not the xor'd plain text. This means that -errors only affect a single block but the cipher is more vulnerable to -attack.

EXAMPLES

-% set ciphertext [DES::des -mode cbc -dir encrypt -key $secret $plaintext]
-% set plaintext [DES::des -mode cbc -dir decrypt -key $secret $ciphertext]
-

-set iv [string repeat \\0 8]
-set Key [DES::Init cbc \\0\\1\\2\\3\\4\\5\\6\\7 $iv]
-set ciphertext [DES::Encrypt $Key "somedata"]
-append ciphertext [DES::Encrypt $Key "moredata"]
-DES::Reset $Key $iv
-set plaintext [DES::Decrypt $Key $ciphertext]
-DES::Final $Key
-

REFERENCES

"Data Encryption Standard", - Federal Information Processing Standards Publication 46-3, 1999, - (http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf)
"TclDES: munitions-grade Tcl scripting" - http://tcldes.sourceforge.net/

AUTHORS

Jochen C Loewer, -Mac Cody, -Pat Thoyts

Bugs, Ideas, Feedback

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

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

Keywords

3DES, DES, block cipher, data integrity, encryption, security

Category

Hashes, checksums, and encryption

Copyright

DELETED embedded/www/tcllib/files/modules/des/tcldes.html Index: embedded/www/tcllib/files/modules/des/tcldes.html ================================================================== --- embedded/www/tcllib/files/modules/des/tcldes.html +++ /dev/null @@ -1,156 +0,0 @@ - -

- -

tclDES(n) 1.1 tcllib "Data Encryption Standard (DES)"

Name

tclDES - Implementation of the DES and triple-DES ciphers

Table Of Contents
Synopsis
Description
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require tclDES 1.1

Description

The tclDES package is a helper package for des.

Please see the documentation of des for details.

Bugs, Ideas, Feedback

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

Keywords

3DES, DES, block cipher, data integrity, encryption, security

Category

Hashes, checksums, and encryption

Copyright

DELETED embedded/www/tcllib/files/modules/des/tcldesjr.html Index: embedded/www/tcllib/files/modules/des/tcldesjr.html ================================================================== --- embedded/www/tcllib/files/modules/des/tcldesjr.html +++ /dev/null @@ -1,156 +0,0 @@ - -

- -

tclDESjr(n) 1.1 tcllib "Data Encryption Standard (DES)"

Name

tclDESjr - Implementation of the DES and triple-DES ciphers

Table Of Contents
Synopsis
Description
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require tclDESjr 1.1

Description

The tclDESjr package is a helper package for des.

Please see the documentation of des for details.

Bugs, Ideas, Feedback

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

Keywords

3DES, DES, block cipher, data integrity, encryption, security

Category

Hashes, checksums, and encryption

Copyright

DELETED embedded/www/tcllib/files/modules/dicttool/dicttool.html Index: embedded/www/tcllib/files/modules/dicttool/dicttool.html ================================================================== --- embedded/www/tcllib/files/modules/dicttool/dicttool.html +++ /dev/null @@ -1,204 +0,0 @@ - -

- -

dicttool(n) 1.0 tcllib "Extensions to the standard "dict" command"

Name

dicttool - Dictionary Tools

Table Of Contents
Synopsis
Description
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.5

ladd varname args
ldelete varname args
dict getnull args
dict print dict
dict is_dict value
rmerge args

Description

The dicttool package enhances the standard dict command with several new -commands. In addition, the package also defines several "creature comfort" list commands as well. -Each command checks to see if a command already exists of the same name before adding itself, -just in case any of these slip into the core.

ladd varname args

This command will add a new instance of each element in args to varname, but only if that element -is not already present.

ldelete varname args

This command will add a delete all instances of each element in args from varname.

dict getnull args

Operates like dict get, however if the key args does not exist, it returns an empty -list instead of throwing an error.

dict print dict

This command will produce a string representation of dict, with each nested branch on -a newline, and indented with two spaces for every level.

dict is_dict value

This command will return true if value can be interpreted as a dict. The command operates in -such a way as to not force an existing dict representation to shimmer into another internal rep.

rmerge args

Return a dict which is the product of a recursive merge of all of the arguments. Unlike dict merge, -this command descends into all of the levels of a dict. Dict keys which end in a : indicate a leaf, which -will be interpreted as a literal value, and not descended into further.

-set items [dict merge {
-  option {color {default: green}}
-} {
-  option {fruit {default: mango}}
-} {
-  option {color {default: blue} fruit {widget: select values: {mango apple cherry grape}}}
-}]
-puts [dict print $items]
-

Prints the following result:

-option {
-  color {
-    default: blue
-  }
-  fruit {
-    widget: select
-    values: {mango apple cherry grape}
-  }
-}
-

Bugs, Ideas, Feedback

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

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

Keywords

dict

Category

Utilities

Copyright

DELETED embedded/www/tcllib/files/modules/dns/tcllib_dns.html Index: embedded/www/tcllib/files/modules/dns/tcllib_dns.html ================================================================== --- embedded/www/tcllib/files/modules/dns/tcllib_dns.html +++ /dev/null @@ -1,372 +0,0 @@ - -

- -

dns(n) 1.4.0 tcllib "Domain Name Service"

Name

dns - Tcl Domain Name Service Client

Table Of Contents
Synopsis
Description
COMMANDS
EXAMPLES
REFERENCES
AUTHORS
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require dns ?1.4.0?

::dns::resolve query ?options?
::dns::configure ?options?
::dns::name token
::dns::address token
::dns::cname token
::dns::result token
::dns::status token
::dns::error token
::dns::reset token
::dns::wait token
::dns::cleanup token
::dns::nameservers

Description

The dns package provides a Tcl only Domain Name Service client. You -should refer to (1) and (2) for information about the DNS protocol or -read resolver(3) to find out how the C library resolves domain names. -The intention of this package is to insulate Tcl scripts -from problems with using the system library resolver for slow name servers. -It may or may not be of practical use. Internet name resolution is a -complex business and DNS is only one part of the resolver. You may -find you are supposed to be using hosts files, NIS or WINS to name a -few other systems. This package is not a substitute for the C library -resolver - it does however implement name resolution over DNS. -The package also extends the package uri to support DNS URIs -(4) of the form dns:what.host.com or -dns://my.nameserver/what.host.com. The dns::resolve -command can handle DNS URIs or simple domain names as a query.

Note: The package defaults to using DNS over TCP -connections. If you wish to use UDP you will need to have the -tcludp package installed and have a version that -correctly handles binary data (> 1.0.4). -This is available at http://tcludp.sourceforge.net/. -If the udp package is present then UDP will be used by -default.

Note: The package supports DNS over TLS (RFC 7858) for -enhanced privacy of DNS queries. Using this feature requires -the TLS package.

COMMANDS

::dns::resolve query ?options?

Resolve a domain name using the DNS protocol. query is -the domain name to be lookup up. This should be either a fully -qualified domain name or a DNS URI.

-nameserver hostname or -server hostname: Specify an alternative name server for this request.
-protocol tcp|udp: Specify the network protocol to use for this request. Can be one of - tcp or udp.
-port portnum: Specify an alternative port.
-search domainlist
-timeout milliseconds: Override the default timeout.
-type TYPE: Specify the type of DNS record you are interested in. Valid values - are A, NS, MD, MF, CNAME, SOA, MB, MG, MR, NULL, WKS, PTR, HINFO, - MINFO, MX, TXT, SPF, SRV, AAAA, AXFR, MAILB, MAILA and *. - See RFC1035 for details about the return values. - See http://spf.pobox.com/ about SPF. - See (3) about AAAA records and RFC2782 for details of SRV records.
-class CLASS: Specify the class of domain name. This is usually IN but may be one - of IN for internet domain names, CS, CH, HS or * for any class.
-recurse boolean: Set to false if you do not want the name server to recursively - act upon your request. Normally set to true.
-command procname: Set a procedure to be called upon request completion. The procedure - will be passed the token as its only argument.
-usetls boolean: Set the true to use DNS over TLS. This will force the use of - TCP and change the default port to 853. Certificate validation is - required so a source of trusted certificate authority certificates - must be provided using -cafile or -cadir.
-cafile filepath: Specify a file containing a collection of trusted certificate - authority certficates. See the update-ca-certificates command - manual page for details or the -CAfile option help from - openssl.
-cadir dirpath: Specify a directory containing trusted certificate authority - certificates. This must be provided if -cafile is not - specified for certificate validation to work when -usetls is - enabled. See the openssl documentation for the required - structure of this directory.

::dns::configure ?options?

The ::dns::configure command is used to setup the dns -package. The server to query, the protocol and domain search path are -all set via this command. If no arguments are provided then a list of -all the current settings is returned. If only one argument then it -must the the name of an option and the value for that option is -returned.

-nameserver hostname: Set the default name server to be used by all queries. The default is - localhost.
-protocol tcp|udp: Set the default network protocol to be used. Default is tcp.
-port portnum: Set the default port to use on the name server. The default is 53.
-search domainlist: Set the domain search list. This is currently not used.
-timeout milliseconds: Set the default timeout value for DNS lookups. Default is 30 seconds.
-loglevel level: Set the log level used for emitting diagnostic messages from this - package. The default is warn. See the log package - for details of the available levels.
-cafile filepath: Set the default file path to be used for the -cafile - option to dns::resolve.
-cadir dirpath: Set the default directory path to be used for the -cadir - option to dns::resolve.

::dns::name token

Returns a list of all domain names returned as an answer to your query.

::dns::address token

Returns a list of the address records that match your query.

::dns::cname token

Returns a list of canonical names (usually just one) matching your query.

::dns::result token

Returns a list of all the decoded answer records provided for your - query. This permits you to extract the result for more unusual query types.

::dns::status token

Returns the status flag. For a successfully completed query this will be - ok. May be error or timeout or eof. - See also ::dns::error

::dns::error token

Returns the error message provided for requests whose status is error. - If there is no error message then an empty string is returned.

::dns::reset token

Reset or cancel a DNS query.

::dns::wait token

Wait for a DNS query to complete and return the status upon completion.

::dns::cleanup token

Remove all state variables associated with the request.

::dns::nameservers

Attempts to return a list of the nameservers currently configured -for the users system. On a unix machine this parses the -/etc/resolv.conf file for nameservers (if it exists) and on Windows -systems we examine certain parts of the registry. If no nameserver can -be found then the loopback address (127.0.0.1) is used as a default.

EXAMPLES

-% set tok [dns::resolve www.tcl.tk]
-::dns::1
-% dns::status $tok
-ok
-% dns::address $tok
-199.175.6.239
-% dns::name $tok
-www.tcl.tk
-% dns::cleanup $tok
-

Using DNS URIs as queries:

-% set tok [dns::resolve "dns:tcl.tk;type=MX"]
-% set tok [dns::resolve "dns://l.root-servers.net/www.tcl.tk"]
-

Reverse address lookup:

-% set tok [dns::resolve 127.0.0.1]
-::dns::1
-% dns::name $tok
-localhost
-% dns::cleanup $tok
-

Using DNS over TLS (RFC 7858):

-% set tok [dns::resolve www.tcl.tk -nameserver dns-tls.bitwiseshift.net  -usetls 1 -cafile /etc/ssl/certs/ca-certificates.crt]
-::dns::12
-% dns::wait $tok
-ok
-% dns::address $tok
-104.25.119.118 104.25.120.118
-

REFERENCES

Mockapetris, P., "Domain Names - Concepts and Facilities", - RFC 1034, November 1987. - (http://www.ietf.org/rfc/rfc1034.txt)
Mockapetris, P., "Domain Names - Implementation and Specification", - RFC 1035, November 1087. - (http://www.ietf.org/rfc/rfc1035.txt)
Thompson, S. and Huitema, C., "DNS Extensions to support IP version 6", - RFC 1886, December 1995. - (http://www.ietf.org/rfc/rfc1886.txt)
Josefsson, S., "Domain Name System Uniform Resource Identifiers", - Internet-Draft, October 2003, - (http://www.ietf.org/internet-drafts/draft-josefsson-dns-url-09.txt)
Gulbrandsen, A., Vixie, P. and Esibov, L., - "A DNS RR for specifying the location of services (DNS SRV)", - RFC 2782, February 2000, - (http://www.ietf.org/rfc/rfc2782.txt)
Ohta, M. "Incremental Zone Transfer in DNS", - RFC 1995, August 1996, - (http://www.ietf.org/rfc/rfc1995.txt)
Hu, Z., etc al. - "Specification for DNS over Transport Layer Security (TLS)", - RFC 7858, May 2016, - (http://www.ietf.org/rfc/rfc7858.txt)

AUTHORS

Pat Thoyts

Bugs, Ideas, Feedback

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

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

Keywords

DNS, domain name service, resolver, rfc 1034, rfc 1035, rfc 1886, rfc 7858

Category

Networking

Copyright

DELETED embedded/www/tcllib/files/modules/dns/tcllib_ip.html Index: embedded/www/tcllib/files/modules/dns/tcllib_ip.html ================================================================== --- embedded/www/tcllib/files/modules/dns/tcllib_ip.html +++ /dev/null @@ -1,478 +0,0 @@ - -

- -

tcllib_ip(n) 1.4 tcllib "Domain Name Service"

Name

tcllib_ip - IPv4 and IPv6 address manipulation

Table Of Contents
Synopsis
Description
COMMANDS
EXAMPLES
REFERENCES
AUTHORS
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require ip ?1.4?

::ip::version address
::ip::is class address
::ip::equal address address
::ip::normalize address
::ip::contract address
::ip::distance ipaddr1 ipaddr2
::ip::nextIp ipaddr ?offset?
::ip::prefix address
::ip::type address
::ip::mask address
::ip::prefixToNative prefix
::ip::nativeToPrefix nativeList|native ?-ipv4?
::ip::intToString number ?-ipv4?
::ip::toInteger ipaddr
::ip::toHex ipaddr
::ip::maskToInt ipmask
::ip::broadcastAddress prefix ?-ipv4?
::ip::maskToLength dottedMask|integerMask|hexMask ?-ipv4?
::ip::lengthToMask maskLength ?-ipv4?
::ip::nextNet ipaddr ipmask ?count? ?-ipv4?
::ip::isOverlap prefix prefix...
::ip::isOverlapNative ?-all? ?-inline? ?-ipv4? hexipaddr hexipmask hexiplist
::ip::ipToLayer2Multicast ipaddr
::ip::ipHostFromPrefix prefix ?-exclude prefixExcludeList?
::ip::reduceToAggregates prefixlist
::ip::longestPrefixMatch ipaddr prefixlist ?-ipv4?
::ip::collapse prefixlist
::ip::subtract prefixlist

Description

This package provides a set of commands to help in parsing, displaying -and comparing internet addresses. The package can handle both IPv4 (1) -and IPv6 (2) address types.

COMMANDS

::ip::version address

Returns the protocol version of the address (4 or 6), -or -1 if the address is neither IPv4 or IPv6.

::ip::is class address

Returns true if the address is a member of the given protocol -class. The class parameter may be either ipv4 or ipv6 -This is effectively a boolean equivalent of the version -command. The class argument may be shortened to 4 or -6.

::ip::equal address address

Compare two address specifications for equivalence. The arguments are -normalized and the address prefix determined (if a mask is -supplied). The normalized addresses are then compared bit-by-bit and -the procedure returns true if they match.

::ip::normalize address

Convert an IPv4 or IPv6 address into a fully expanded version. There -are various shorthand ways to write internet addresses, missing out -redundant parts or digits. This procedure is the opposite of -contract.

::ip::contract address

Convert a normalized internet address into a more compact form -suitable for displaying to users.

::ip::distance ipaddr1 ipaddr2

This command computes the (integer) distance from IPv4 address -ipaddr1 to IPv4 address ipaddr2, i.e. "ipaddr2 - ipaddr1"

-   % ::ip::distance 1.1.1.1  1.1.1.5
-   4
-

::ip::nextIp ipaddr ?offset?

This command adds the integer offset to the IPv4 address ipaddr -and returns the new IPv4 address.

-   % ::ip::distance 1.1.1.1  4
-   1.1.1.5
-

::ip::prefix address

Returns the address prefix generated by masking the address part with -the mask if provided. If there is no mask then it is equivalent to -calling normalize

::ip::type address

::ip::mask address

If the address supplied includes a mask then this is returned -otherwise returns an empty string.

::ip::prefixToNative prefix

This command converts the string prefix from dotted form -(<ipaddr>/<mask> format) to native (hex) form. Returns a list -containing two elements, ipaddress and mask, in this order, in -hexadecimal notation.

-   % ip::prefixToNative 1.1.1.0/24
-   0x01010100 0xffffff00
-

::ip::nativeToPrefix nativeList|native ?-ipv4?

This command converts from native (hex) form to dotted form. -It is the complement of ::ip::prefixToNative.

list nativeList (in): List of several ip addresses in native form. The native form is a list -as returned by ::ip::prefixToNative.
list native (in): A list as returned by ::ip::prefixToNative.

The command returns a list of addresses in dotted form if it was -called with a list of addresses. Otherwise a single address in dotted -form is returned.

-   % ip::nativeToPrefix {0x01010100 0xffffff00} -ipv4
-   1.1.1.0/24
-

::ip::intToString number ?-ipv4?

This command converts from an ip address specified as integer number -to dotted form.

-       ip::intToString 4294967295
-       255.255.255.255
-

::ip::toInteger ipaddr

This command converts a dotted form ip into an integer number.

-   % ::ip::toInteger 1.1.1.0
-   16843008
-

::ip::toHex ipaddr

This command converts dotted form ip into a hexadecimal number.

-   % ::ip::toHex 1.1.1.0
-   0x01010100
-

::ip::maskToInt ipmask

This command convert an ipmask in either dotted (255.255.255.0) form -or mask length form (24) into an integer number.

-   ::ip::maskToInt 24
-   4294967040
-

::ip::broadcastAddress prefix ?-ipv4?

This commands returns a broadcast address in dotted form for the given -route prefix, either in the form "addr/mask", or in native -form. The result is in dotted form.

-   ::ip::broadcastAddress 1.1.1.0/24
-   1.1.1.255
-   ::ip::broadcastAddress {0x01010100 0xffffff00}
-   0x010101ff
-

::ip::maskToLength dottedMask|integerMask|hexMask ?-ipv4?

This command converts the dotted or integer form of an ipmask to -the mask length form.

-   ::ip::maskToLength 0xffffff00 -ipv4
-   24
-   % ::ip::maskToLength 255.255.255.0
-   24
-

::ip::lengthToMask maskLength ?-ipv4?

This command converts an ipmask in mask length form to its dotted -form.

-   ::ip::lengthToMask 24
-   255.255.255.0
-

::ip::nextNet ipaddr ipmask ?count? ?-ipv4?

This command returns an ipaddress in the same position in the -count next network. The default value for count is -1.

The address can be specified as either integer number or in dotted -form. The mask can be specified as either integer number, dotted form, -or mask length form.

The result is in hex form.

::ip::isOverlap prefix prefix...

This command checks if the given ip prefixes overlap. All arguments -are in dotted "addr/mask" form. All arguments after the first prefix -are compared against the first prefix. The result is a boolean -value. It is true if an overlap was found for any of the prefixes.

-  % ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32
-  0
-  ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32 1.1.1.1/32
-  1
-

::ip::isOverlapNative ?-all? ?-inline? ?-ipv4? hexipaddr hexipmask hexiplist

This command is similar to ::ip::isOverlap, however the -arguments are in the native form, and the form of the result is under -greater control of the caller. -If the option -all is specified it checks all addresses for -overlap, not only until the first one is found. -If the option -inline is specified the command returns the -overlapping prefix instead of index values.

The result of the command is, depending on the specified options,

no options: The index of the first overlap found, or 0 if there is none.
-all: A list containing the indices of all overlaps found, or an empty list -if there are none.
-inline: The first overlapping prefix, or an empoty string if there is none.
-all -inline: A list containing the prefixes of all overlaps found, or an empty list -if there are none.

-  % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff}}
-  0
-  % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff} {0x01010101 0xffffffff}}
-  2
-

::ip::ipToLayer2Multicast ipaddr

This command an converts ipv4 address in dotted form into a layer 2 -multicast address, also in dotted form.

-  % ::ip::ipToLayer2Multicast 224.0.0.2
-  01.00.5e.00.00.02
-

::ip::ipHostFromPrefix prefix ?-exclude prefixExcludeList?

This command returns a host address from a prefix in the form -"ipaddr/masklen", also making sure that the result is not an address -found in the prefixExcludeList. -The result is an ip address in dotted form.

-  %::ip::ipHostFromPrefix  1.1.1.5/24
-  1.1.1.1
-  %::ip::ipHostFromPrefix  1.1.1.1/32
-  1.1.1.1
-

::ip::reduceToAggregates prefixlist

This command finds nets that overlap and filters out the more specific -nets. The prefixes are in either addr/mask form or in native format. -The result is a list containing the non-overlapping ip prefixes from -the input.

-  % ::ip::reduceToAggregates {1.1.1.0/24 1.1.0.0/8  2.1.1.0/24 1.1.1.1/32 }
-  1.0.0.0/8 2.1.1.0/24
-

::ip::longestPrefixMatch ipaddr prefixlist ?-ipv4?

This command finds longest prefix match from set of prefixes, given a -specific host address. The prefixes in the list are in either native -or dotted form, whereas the host address is in either ipprefix format, -dotted form, or integer form. -The result is the prefix which is the most specific match to the host -address.

-  % ::ip::longestPrefixMatch 1.1.1.1 {1.1.1.0/24 1.0.0.0/8  2.1.1.0/24 1.1.1.0/28 }
-  1.1.1.0/28
-

::ip::collapse prefixlist

This commands takes a list of prefixes and returns a list prefixes -with the largest possible subnet masks covering the input, in this -manner collapsing adjacent prefixes into larger ranges.

This is different from ::ip::reduceToAggregates in that -the latter only removes specific nets from a list when they are -covered by other elements of the input whereas this command actively -merges nets into larger ranges when they are adjacent to each other.

-% ::ip::collapse {1.2.2.0/24 1.2.3.0/24}
-1.2.2.0/23
-

::ip::subtract prefixlist

This command takes a list of prefixes, some of which are prefixed by a -dash. These latter negative prefixes are used to punch holes -into the ranges described by the other, positive, -prefixes. I.e. the negative prefixes are subtracted frrom the positive -ones, resulting in a larger list of describes describing the covered -ranges only as positives.

EXAMPLES

-% ip::version ::1
-6
-% ip::version 127.0.0.1
-4
-

-% ip::normalize 127/8
-127.0.0.0/8
-% ip::contract 192.168.0.0
-192.168
-%
-% ip::normalize fec0::1
-fec0:0000:0000:0000:0000:0000:0000:0001
-% ip::contract fec0:0000:0000:0000:0000:0000:0000:0001
-fec0::1
-

-% ip::equal 192.168.0.4/16 192.168.0.0/16
-1
-% ip::equal fec0::1/10 fec0::fe01/10
-1
-

REFERENCES

Postel, J. "Internet Protocol." RFC 791, September 1981, - (http://www.ietf.org/rfc/rfc791.txt)
Hinden, R. and Deering, S., - "Internet Protocol Version 6 (IPv6) Addressing Architecture", - RFC 3513, April 2003 - (http://www.ietf.org/rfc/rfc3513.txt)

AUTHORS

Pat Thoyts

Bugs, Ideas, Feedback

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

Keywords

internet address, ip, ipv4, ipv6, rfc 3513

Category

Networking

Copyright

DELETED embedded/www/tcllib/files/modules/docstrip/docstrip.html Index: embedded/www/tcllib/files/modules/docstrip/docstrip.html ================================================================== --- embedded/www/tcllib/files/modules/docstrip/docstrip.html +++ /dev/null @@ -1,518 +0,0 @@ -

- -

docstrip(n) 1.2 tcllib "Literate programming tool"

Name

docstrip - Docstrip style source code extraction

Table Of Contents
Synopsis
Description
File format
Commands
Document structure
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require docstrip ?1.2?

docstrip::extract text terminals ?option value ...?
docstrip::sourcefrom filename terminals ?option value ...?

Description

Docstrip is a tool created to support a brand of Literate -Programming. It is most common in the (La)TeX community, where it -is being used for pretty much everything from the LaTeX core and up, -but there is nothing about docstrip which prevents using it -for other types of software.

In short, the basic principle of literate programming is that program -source should primarily be written and structured to suit the -developers (and advanced users who want to peek "under the hood"), not -to suit the whims of a compiler or corresponding source code consumer. -This means literate sources often need some kind of "translation" to an -illiterate form that dumb software can understand. -The docstrip Tcl package handles this translation.

Even for those who do not whole-hartedly subscribe to the philosophy -behind literate programming, docstrip can bring greater -clarity to in particular:

programs employing non-obvious mathematics
projects where separate pieces of code, perhaps in - different languages, need to be closely coordinated.

The first is by providing access to much more powerful typographical -features for source code comments than are possible in plain text. -The second is because all the separate pieces of code can be kept -next to each other in the same source file.

The way it works is that the programmer edits directly only one or -several "master" source code files, from which docstrip -generates the more traditional "source" files compilers or the like -would expect. The master sources typically contain a large amount of -documentation of the code, sometimes even in places where the code -consumers would not allow any comments. The etymology of "docstrip" -is that this documentation was stripped away (although -"code extraction" might be a better description, as it has always -been a matter of copying selected pieces of the master source rather -than deleting text from it). -The docstrip Tcl package contains a reimplementation of -the basic extraction functionality from the docstrip -program, and thus makes it possible for a Tcl interpreter to read -and interpret the master source files directly.

Readers who are not previously familiar with docstrip but -want to know more about it may consult the following sources.

The tclldoc package and class, - http://ctan.org/tex-archive/macros/latex/contrib/tclldoc/.
The DocStrip utility, - http://ctan.org/tex-archive/macros/latex/base/docstrip.dtx.
The doc and shortvrb Packages, - http://ctan.org/tex-archive/macros/latex/base/doc.dtx.
Chapter 14 of - The LaTeX Companion (second edition), - Addison-Wesley, 2004; ISBN 0-201-36299-6.

File format

The basic unit docstrip operates on are the lines of -a master source file. Extraction consists of selecting some of these -lines to be copied from input text to output text. The basic -distinction is that between code lines (which are copied and -do not begin with a percent character) and comment lines -(which begin with a percent character and are not copied).

-   docstrip::extract [join {
-     {% comment}
-     {% more comment !"#$%&/(}
-     {some command}
-     { % blah $blah "Not a comment."}
-     {% abc; this is comment}
-     {# def; this is code}
-     {ghi}
-     {% jkl}
-   } \n] {}
-

returns the same sequence of lines as

-   join {
-     {some command}
-     { % blah $blah "Not a comment."}
-     {# def; this is code}
-     {ghi} ""
-   } \n
-

It does not matter to docstrip what format is used for the -documentation in the comment lines, but in order to do better than -plain text comments, one typically uses some markup language. Most -commonly LaTeX is used, as that is a very established standard and -also provides the best support for mathematical formulae, but the -docstrip::util package also gives some support for -doctools-like markup.

Besides the basic code and comment lines, there are also -guard lines, which begin with the two characters '%<', and -meta-comment lines, which begin with the two characters -'%%'. Within guard lines there is furthermore the distinction between -verbatim guard lines, which begin with '%<<', and ordinary -guard lines, where the '%<' is not followed by another '<'. The last -category is by far the most common.

Ordinary guard lines conditions extraction of the code line(s) they -guard by the value of a boolean expression; the guarded block of -code lines will only be included if the expression evaluates to true. -The syntax of an ordinary guard line is one of

-    '%' '<' STARSLASH EXPRESSION '>'
-    '%' '<' PLUSMINUS EXPRESSION '>' CODE
-

where

-    STARSLASH  ::=  '*' | '/'
-    PLUSMINUS  ::=  | '+' | '-'
-    EXPRESSION ::= SECONDARY | SECONDARY ',' EXPRESSION
-                 | SECONDARY '|' EXPRESSION
-    SECONDARY  ::= PRIMARY | PRIMARY '&' SECONDARY
-    PRIMARY    ::= TERMINAL | '!' PRIMARY | '(' EXPRESSION ')'
-    CODE       ::= { any character except end-of-line }
-

Comma and vertical bar both denote 'or'. Ampersand denotes 'and'. -Exclamation mark denotes 'not'. A TERMINAL can be any nonempty string -of characters not containing '>', '&', '|', comma, '(', or ')', -although the docstrip manual is a bit restrictive and only -guarantees proper operation for strings of letters (although even -the LaTeX core sources make heavy use also of digits in TERMINALs). -The second argument of docstrip::extract is the list of those -TERMINALs that should count as having the value 'true'; all other -TERMINALs count as being 'false' when guard expressions are evaluated.

In the case of a '%<*EXPRESSION>' guard, the lines guarded are -all lines up to the next '%</EXPRESSION>' guard with the same -EXPRESSION (compared as strings). The blocks of code delimited -by such '*' and '/' guard lines must be properly nested.

-   set text [join {
-      {begin}
-      {%<*foo>}
-      {1}
-      {%<*bar>}
-      {2}
-      {%</bar>}
-      {%<*!bar>}
-      {3}
-      {%</!bar>}
-      {4}
-      {%</foo>}
-      {5}
-      {%<*bar>}
-      {6}
-      {%</bar>}
-      {end}
-   } \n]
-   set res [docstrip::extract $text foo]
-   append res [docstrip::extract $text {foo bar}]
-   append res [docstrip::extract $text bar]
-

sets $res to the result of

-   join {
-      {begin}
-      {1}
-      {3}
-      {4}
-      {5}
-      {end}
-      {begin}
-      {1}
-      {2}
-      {4}
-      {5}
-      {6}
-      {end}
-      {begin}
-      {5}
-      {6}
-      {end} ""
-   } \n
-

In guard lines without a '*', '/', '+', or '-' modifier after the -'%<', the guard applies only to the CODE following the '>' on that -single line. A '+' modifier is equivalent to no modifier. A '-' -modifier is like the case with no modifier, but the expression is -implicitly negated, i.e., the CODE of a '%<-' guard line is only -included if the expression evaluates to false.

Metacomment lines are "comment lines which should not be stripped -away", but be extracted like code lines; these are sometimes used for -copyright notices and similar material. The '%%' prefix is however -not kept, but substituted by the current -metaprefix, which -is customarily set to some "comment until end of line" character (or -character sequence) of the language of the code being extracted.

-   set text [join {
-      {begin}
-      {%<foo> foo}
-      {%<+foo>plusfoo}
-      {%<-foo>minusfoo}
-      {middle}
-      {%% some metacomment}
-      {%<*foo>}
-      {%%another metacomment}
-      {%</foo>}
-      {end}
-   } \n]
-   set res [docstrip::extract $text foo -metaprefix {# }]
-   append res [docstrip::extract $text bar -metaprefix {#}]
-

sets $res to the result of

-   join {
-      {begin}
-      { foo}
-      {plusfoo}
-      {middle}
-      {#  some metacomment}
-      {# another metacomment}
-      {end}
-      {begin}
-      {minusfoo}
-      {middle}
-      {# some metacomment}
-      {end} ""
-   } \n
-

Verbatim guards can be used to force code line -interpretation of a block of lines even if some of them happen to look -like any other type of lines to docstrip. A verbatim guard has the -form '%<<END-TAG' and the verbatim block is terminated by the -first line that is exactly '%END-TAG'.

-   set text [join {
-      {begin}
-      {%<*myblock>}
-      {some stupid()}
-      {   #computer<program>}
-      {%<<QQQ-98765}
-      {% These three lines are copied verbatim (including percents}
-      {%% even if -metaprefix is something different than %%).}
-      {%</myblock>}
-      {%QQQ-98765}
-      {   using*strange@programming<language>}
-      {%</myblock>}
-      {end}
-   } \n]
-   set res [docstrip::extract $text myblock -metaprefix {# }]
-   append res [docstrip::extract $text {}]
-

sets $res to the result of

-   join {
-      {begin}
-      {some stupid()}
-      {   #computer<program>}
-      {% These three lines are copied verbatim (including percents}
-      {%% even if -metaprefix is something different than %%).}
-      {%</myblock>}
-      {   using*strange@programming<language>}
-      {end}
-      {begin}
-      {end} ""
-   } \n
-

The processing of verbatim guards takes place also inside blocks of -lines which due to some outer block guard will not be copied.

The final piece of docstrip syntax is that extraction -stops at a line that is exactly "\endinput"; this is often used to -avoid copying random whitespace at the end of a file. In the unlikely -case that one wants such a code line, one can protect it with a -verbatim guard.

Commands

The package defines two commands.

docstrip::extract text terminals ?option value ...?

The extract command docstrips the text and returns the - extracted lines of code, as a string with each line terminated with - a newline. The terminals is the list of those guard - expression terminals which should evaluate to true. - The available options are:

-annotate lines

Requests the specified number of lines of annotation to follow - each extracted line in the result. Defaults to 0. Annotation lines - are mostly useful when the extracted lines are to undergo some - further transformation. A first annotation line is a list of three - elements: line type, prefix removed in extraction, and prefix - inserted in extraction. The line type is one of: 'V' (verbatim), - 'M' (metacomment), '+' (+ or no modifier guard line), '-' (- - modifier guard line), '.' (normal line). A second annotation line - is the source line number. A third annotation line is the current - stack of block guards. Requesting more than three lines of - annotation is currently not supported.

-metaprefix string

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

-onerror keyword

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

ignore: Just ignore the error; continue as if nothing happened.
puts: Write an error message to stderr, then continue - processing.
throw: Throw an error. The -errorcode is set to a list whose - first element is DOCSTRIP, second element is the - type of error, and third element is the line number where - the error is detected. This is the default.

-trimlines boolean

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

It should be remarked that the terminals are often called - "options" in the context of the docstrip program, since - these specify which optional code fragments should be included.

docstrip::sourcefrom filename terminals ?option value ...?

The sourcefrom command is a docstripping emulation of - source. It opens the file filename, reads it, closes it, - docstrips the contents as specified by the terminals, and - evaluates the result in the local context of the caller, during - which time the info script value will be the - filename. The options are passed on to fconfigure to - configure the file before its contents are read. The - -metaprefix is set to '#', all other extract - options have their default values.

Document structure

The file format (as described above) determines whether a master -source code file can be processed correctly by docstrip, -but the usefulness of the format is to no little part also dependent -on that the code and comment lines together constitute a well-formed -document.

For a document format that does not require any non-Tcl software, see -the ddt2man command in the docstrip::util package. It -is suggested that files employing that document format are given the -suffix ".ddt", to distinguish them from the more traditional -LaTeX-based ".dtx" files.

Master source files with ".dtx" extension are usually set up so -that they can be typeset directly by latex without any -support from other files. This is achieved by beginning the file -with the lines

-   % \iffalse
-   %<*driver>
-   \documentclass{tclldoc}
-   \begin{document}
-   \DocInput{filename.dtx}
-   \end{document}
-   %</driver>
-   % \fi
-

or some variation thereof. The trick is that the file gets read twice. -With normal LaTeX reading rules, the first two lines are comments and -therefore ignored. The third line is the document preamble, the fourth -line begins the document body, and the sixth line ends the document, -so LaTeX stops there — non-comments below that point in -the file are never subjected to the normal LaTeX reading rules. Before -that, however, the \DocInput command on the fifth line is processed, -and that does two things: it changes the interpretation of '%' from -"comment" to "ignored", and it inputs the file specified in the -argument (which is normally the name of the file the command is in). -It is this second time that the file is being read that the comments -and code in it are typeset.

The function of the \iffalse ... \fi is to skip lines two to seven -on this second time through; this is similar to the "if 0 { ... }" -idiom for block comments in Tcl code, and it is needed here because -(amongst other things) the \documentclass command may only be -executed once. The function of the <driver> guards is to prevent this -short piece of LaTeX code from being extracted by docstrip. -The total effect is that the file can function both as a LaTeX -document and as a docstrip master source code file.

It is not necessary to use the tclldoc document class, but that does -provide a number of features that are convenient for ".dtx" -files containing Tcl code. More information on this matter can be -found in the references above.

Keywords

.dtx, LaTeX, docstrip, documentation, literate programming, source

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/docstrip/docstrip_util.html Index: embedded/www/tcllib/files/modules/docstrip/docstrip_util.html ================================================================== --- embedded/www/tcllib/files/modules/docstrip/docstrip_util.html +++ /dev/null @@ -1,674 +0,0 @@ - -

- -

docstrip_util(n) 1.3.1 tcllib "Literate programming tool"

Name

docstrip_util - Docstrip-related utilities

Table Of Contents
Synopsis
Description
Package indexing commands
Source processing commands
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require docstrip ?1.2?
package require docstrip::util ?1.3.1?

pkgProvide name version terminals
pkgIndex ?terminal ...?
fileoptions ?option value ...?
docstrip::util::index_from_catalogue dir pattern ?option value ...?
docstrip::util::modules_from_catalogue target source ?option value ...?
docstrip::util::classical_preamble metaprefix message target ?source terminals ...?
docstrip::util::classical_postamble metaprefix message target ?source terminals ...?
docstrip::util::packages_provided text ?setup-script?
docstrip::util::ddt2man text
docstrip::util::guards subcmd text
docstrip::util::patch source-var terminals fromtext diff ?option value ...?
docstrip::util::thefile filename ?option value ...?
docstrip::util::import_unidiff diff-text ?warning-var?

Description

The docstrip::util package is meant for collecting various -utility procedures that are mainly useful at installation or -development time. It is separate from the base package to avoid -overhead when the latter is used to source code.

Package indexing commands

Like raw ".tcl" files, code lines in docstrip source files can -be searched for package declarations and corresponding indices -constructed. A complication is however that one cannot tell from the -code blocks themselves which will fit together to make a working -package; normally that information would be found in an accompanying -".ins" file, but parsing one of those is not an easy task. -Therefore docstrip::util introduces an alternative encoding -of such information, in the form of a declarative Tcl script: the -catalogue (of the contents in a source file).

The special commands which are available inside a catalogue are:

pkgProvide name version terminals: Declares that the code for a package with name name and - version version is made up from those modules in the source - file which are selected by the terminals list of guard - expression terminals. This code should preferably not contain a - package provide command for the package, as one - will be provided by the package loading mechanisms.
pkgIndex ?terminal ...?: Declares that the code for a package is made up from those modules - in the source file which are selected by the listed guard - expression terminals. The name and version of this package is - determined from package provide command(s) found - in that code (hence there must be such a command in there).
fileoptions ?option value ...?: Declares the fconfigure options that should be in force when - reading the source; this can usually be ignored for pure ASCII - files, but if the file needs to be interpreted according to some - other -encoding then this is how to specify it. The - command should normally appear first in the catalogue, as it takes - effect only for commands following it.

Other Tcl commands are supported too — a catalogue is -parsed by being evaluated in a safe interpreter — but they -are rarely needed. To allow for future extensions, unknown commands -in the catalogue are silently ignored.

To simplify distribution of catalogues together with their source -files, the catalogue is stored in the source file itself as -a module selected by the terminal 'docstrip.tcl::catalogue'. -This supports both the style of collecting all catalogue lines in one -place and the style of putting each catalogue line in close proximity -of the code that it declares.

Putting catalogue entries next to the code they declare may look as -follows

-%    First there's the catalogue entry
-%    \begin{tcl}
-%<docstrip.tcl::catalogue>pkgProvide foo::bar 1.0 {foobar load}
-%    \end{tcl}
-%    second a metacomment used to include a copyright message
-%    \begin{macrocode}
-%<*foobar>
-%% This file is placed in the public domain.
-%    \end{macrocode}
-%    third the package implementation
-%    \begin{tcl}
-namespace eval foo::bar {
-   # ... some clever piece of Tcl code elided ...
-%    \end{tcl}
-%    which at some point may have variant code to make use of a
-%    |load|able extension
-%    \begin{tcl}
-%<*load>
-   load [file rootname [info script]][info sharedlibextension]
-%</load>
-%<*!load>
-   # ... even more clever scripted counterpart of the extension
-   # also elided ...
-%</!load>
-}
-%</foobar>
-%    \end{tcl}
-%    and that's it!
-

The corresponding set-up with pkgIndex would be

-%    First there's the catalogue entry
-%    \begin{tcl}
-%<docstrip.tcl::catalogue>pkgIndex foobar load
-%    \end{tcl}
-%    second a metacomment used to include a copyright message
-%    \begin{tcl}
-%<*foobar>
-%% This file is placed in the public domain.
-%    \end{tcl}
-%    third the package implementation
-%    \begin{tcl}
-package provide foo::bar 1.0
-namespace eval foo::bar {
-   # ... some clever piece of Tcl code elided ...
-%    \end{tcl}
-%    which at some point may have variant code to make use of a
-%    |load|able extension
-%    \begin{tcl}
-%<*load>
-   load [file rootname [info script]][info sharedlibextension]
-%</load>
-%<*!load>
-   # ... even more clever scripted counterpart of the extension
-   # also elided ...
-%</!load>
-}
-%</foobar>
-%    \end{tcl}
-%    and that's it!
-

docstrip::util::index_from_catalogue dir pattern ?option value ...?

This command is a sibling of the standard pkg_mkIndex - command, in that it adds package entries to "pkgIndex.tcl" - files. The difference is that it indexes docstrip-style - source files rather than raw ".tcl" or loadable library files. - Only packages listed in the catalogue of a file are considered.

The dir argument is the directory in which to look for files - (and whose "pkgIndex.tcl" file should be amended). - The pattern argument is a glob pattern of files to look - into; a typical value would be *.dtx or - *.{dtx,ddt}. Remaining arguments are option-value pairs, - where the supported options are:

-recursein dirpattern: If this option is given, then the index_from_catalogue - operation will be repeated in each subdirectory whose name - matches the dirpattern. -recursein * will - cause the entire subtree rooted at dir to be indexed.
-sourceconf dictionary: Specify fileoptions to use when reading the catalogues of - files (and also for reading the packages if the catalogue does - not contain a fileoptions command). Defaults to being - empty. Primarily useful if your system encoding is very different - from that of the source file (e.g., one is a two-byte encoding - and the other is a one-byte encoding). ascii and - utf-8 are not very different in that sense.
-options terminals: The terminals is a list of terminals in addition to - docstrip.tcl::catalogue that should be held as true when - extracting the catalogue. Defaults to being empty. This makes it - possible to make use of "variant sections" in the catalogue - itself, e.g. gaurd some entries with an extra "experimental" and - thus prevent them from appearing in the index unless that is - generated with "experimental" among the -options.
-report boolean: If the boolean is true then the return value will be a - textual, probably multiline, report on what was done. Defaults - to false, in which case there is no particular return value.
-reportcmd commandPrefix: Every item in the report is handed as an extra argument to the - command prefix. Since index_from_catalogue would typically - be used at a rather high level in installation scripts and the - like, the commandPrefix defaults to - "puts stdout". - Use list to effectively disable this feature. The return - values from the prefix are ignored.

The package ifneeded scripts that are generated contain - one package require docstrip command and one - docstrip::sourcefrom command. If the catalogue entry was - of the pkgProvide kind then the package ifneeded - script also contains the package provide command.

Note that index_from_catalogue never removes anything from an - existing "pkgIndex.tcl" file. Hence you may need to delete it - (or have pkg_mkIndex recreate it from scratch) before running - index_from_catalogue to update some piece of information, such - as a package version number.

docstrip::util::modules_from_catalogue target source ?option value ...?

This command is an alternative to index_from_catalogue which - creates Tcl Module (".tm") files rather than - "pkgIndex.tcl" entries. Since this action is more similar to - what docstrip classically does, it has features for - putting pre- and postambles on the generated files.

The source argument is the name of the source file to - generate ".tm" files from. The target argument is the - directory which should count as a module path, i.e., this is what - the relative paths derived from package names are joined to. The - supported options are:

-preamble message: A message to put in the preamble (initial block of comments) of - generated files. Defaults to a space. May be several lines, which - are then separated by newlines. Traditionally used for copyright - notices or the like, but metacomment lines provide an alternative - to that.
-postamble message: Like -preamble, but the message is put at the end of the - file instead of the beginning. Defaults to being empty.
-sourceconf dictionary: Specify fileoptions to use when reading the catalogue of - the source (and also for reading the packages if the - catalogue does not contain a fileoptions command). Defaults - to being empty. Primarily useful if your system encoding is very - different from that of the source file (e.g., one is a two-byte - encoding and the other is a one-byte encoding). ascii and - utf-8 are not very different in that sense.
-options terminals: The terminals is a list of terminals in addition to - docstrip.tcl::catalogue that should be held as true when - extracting the catalogue. Defaults to being empty. This makes it - possible to make use of "variant sections" in the catalogue - itself, e.g. gaurd some entries with an extra "experimental" guard - and thus prevent them from contributing packages unless those are - generated with "experimental" among the -options.
-formatpreamble commandPrefix: Command prefix used to actually format the preamble. Takes four - additional arguments message, targetFilename, - sourceFilename, and terminalList and returns a fully - formatted preamble. Defaults to using classical_preamble - with a metaprefix of '##'.
-formatpostamble commandPrefix: Command prefix used to actually format the postamble. Takes four - additional arguments message, targetFilename, - sourceFilename, and terminalList and returns a fully - formatted postamble. Defaults to using classical_postamble - with a metaprefix of '##'.
-report boolean: If the boolean is true (which is the default) then the return - value will be a textual, probably multiline, report on what was - done. If it is false then there is no particular return value.
-reportcmd commandPrefix: Every item in the report is handed as an extra argument to this - command prefix. Defaults to list, which effectively disables - this feature. The return values from the prefix are ignored. Use - for example "puts stdout" to get report items - written immediately to the terminal.

An existing file of the same name as one to be created will be - overwritten.

docstrip::util::classical_preamble metaprefix message target ?source terminals ...?

This command returns a preamble in the classical - docstrip style

-##
-## This is `TARGET',
-## generated by the docstrip::util package.
-##
-## The original source files were:
-##
-## SOURCE (with options: `foo,bar')
-##
-## Some message line 1
-## line2
-## line3
-

if called as

-docstrip::util::classical_preamble {##}\
-  "\nSome message line 1\nline2\nline3" TARGET SOURCE {foo bar}
-

The command supports preambles for files generated from multiple - sources, even though modules_from_catalogue at present does - not need that.

docstrip::util::classical_postamble metaprefix message target ?source terminals ...?

This command returns a postamble in the classical - docstrip style

-## Some message line 1
-## line2
-## line3
-##
-## End of file `TARGET'.
-

if called as

-docstrip::util::classical_postamble {##}\
-  "Some message line 1\nline2\nline3" TARGET SOURCE {foo bar}
-

In other words, the source and terminals arguments are - ignored, but supported for symmetry with classical_preamble.

docstrip::util::packages_provided text ?setup-script?

This command returns a list where every even index element is the - name of a package provided by text when that is - evaluated as a Tcl script, and the following odd index element is - the corresponding version. It is used to do package indexing of - extracted pieces of code, in the manner of pkg_mkIndex.

One difference to pkg_mkIndex is that the text gets - evaluated in a safe interpreter. package require commands - are silently ignored, as are unknown commands (which includes - source and load). Other errors cause - processing of the text to stop, in which case only those - package declarations that had been encountered before the error - will be included in the return value.

The setup-script argument can be used to customise the - evaluation environment, if the code in text has some very - special needs. The setup-script is evaluated in the local - context of the packages_provided procedure just before the - text is processed. At that time, the name of the slave - command for the safe interpreter that will do this processing is - kept in the local variable c. To for example copy the - contents of the ::env array to the safe interpreter, one - might use a setup-script of

  $c eval [list array set env [array get ::env]]

Source processing commands

Unlike the previous group of commands, which would use -docstrip::extract to extract some code lines and then process -those further, the following commands operate on text consisting of -all types of lines.

docstrip::util::ddt2man text

The ddt2man command reformats text from the general - docstrip format to doctools ".man" format - (Tcl Markup Language for Manpages). The different line types are - treated as follows:

comment and metacomment lines: The '%' and '%%' prefixes are removed, the rest of the text is - kept as it is.
empty lines: These are kept as they are. (Effectively this means that they will - count as comment lines after a comment line and as code lines - after a code line.)
code lines: example_begin and example_end commands are placed - at the beginning and end of every block of consecutive code - lines. Brackets in a code line are converted to lb and - rb commands.
verbatim guards: These are processed as usual, so they do not show up in the - result but every line in a verbatim block is treated as a code - line.
other guards: These are treated as code lines, except that the actual guard is - emphasised.

At the time of writing, no project has employed doctools - markup in master source files, so experience of what works well is - not available. A source file could however look as follows

-% [manpage_begin gcd n 1.0]
-% [keywords divisor]
-% [keywords math]
-% [moddesc {Greatest Common Divisor}]
-% [require gcd [opt 1.0]]
-% [description]
-%
-% [list_begin definitions]
-% [call [cmd gcd] [arg a] [arg b]]
-%   The [cmd gcd] procedure takes two arguments [arg a] and [arg b] which
-%   must be integers and returns their greatest common divisor.
-proc gcd {a b} {
-%   The first step is to take the absolute values of the arguments.
-%   This relieves us of having to worry about how signs will be treated
-%   by the remainder operation.
-   set a [expr {abs($a)}]
-   set b [expr {abs($b)}]
-%   The next line does all of Euclid's algorithm! We can make do
-%   without a temporary variable, since $a is substituted before the
-%   [lb]set a $b[rb] and thus continues to hold a reference to the
-%   "old" value of [var a].
-   while {$b>0} { set b [expr { $a % [set a $b] }] }
-%   In Tcl 8.3 we might want to use [cmd set] instead of [cmd return]
-%   to get the slight advantage of byte-compilation.
-%<tcl83>  set a
-%<!tcl83>   return $a
-}
-% [list_end]
-%
-% [manpage_end]
-

If the above text is fed through docstrip::util::ddt2man then - the result will be a syntactically correct doctools - manpage, even though its purpose is a bit different.

It is suggested that master source code files with doctools - markup are given the suffix ".ddt", hence the "ddt" in - ddt2man.

docstrip::util::guards subcmd text

The guards command returns information (mostly of a - statistical nature) about the ordinary docstrip guards that occur - in the text. The subcmd selects what is returned.

counts: List the guard expression terminals with counts. The format of - the return value is a dictionary which maps the terminal name to - the number of occurencies of it in the file.
exprcount: List the guard expressions with counts. The format of the return - value is a dictionary which maps the expression to the number of - occurencies of it in the file.
exprerr: List the syntactically incorrect guard expressions (e.g. - parentheses do not match, or a terminal is missing). The return - value is a list, with the elements in no particular order.
expressions: List the guard expressions. The return value is a list, with the - elements in no particular order.
exprmods: List the guard expressions with modifiers. The format of the return - value is a dictionary where each index is a guard expression and - each entry is a string with one character for every guard line that - has this expression. The characters in the entry specify what - modifier was used in that line: +, -, *, /, or (for guard without - modifier:) space. This is the most primitive form of the - information gathered by guards.
names: List the guard expression terminals. The return value is a list, - with the elements in no particular order.
rotten: List the malformed guard lines (this does not include lines where - only the expression is malformed, though). The format of the return - value is a dictionary which maps line numbers to their contents.

docstrip::util::patch source-var terminals fromtext diff ?option value ...?

This command tries to apply a diff file (for example a - contributed patch) that was computed for a generated file to the - docstrip source. This can be useful if someone has - edited a generated file, thus mistaking it for being the source. - This command makes no presumptions which are specific for the case - that the generated file is a Tcl script.

patch requires that the source file to patch is kept as a - list of lines in a variable, and the name of that variable in the - calling context is what goes into the source-var argument. - The terminals is the list of terminals used to extract the - file that has been patched. The diff is the actual diff to - apply (in a format as explained below) and the fromtext is - the contents of the file which served as "from" when the diff was - computed. Options can be used to further control the process.

The process works by "lifting" the hunks in the diff from - generated to source file, and then applying them to the elements of - the source-var. In order to do this lifting, it is necessary - to determine how lines in the fromtext correspond to elements - of the source-var, and that is where the terminals come - in; the source is first extracted under the given - terminals, and the result of that is then matched against - the fromtext. This produces a map which translates line - numbers stated in the diff to element numbers in - source-var, which is what is needed to lift the hunks.

The reason that both the terminals and the fromtext - must be given is twofold. First, it is very difficult to keep track - of how many lines of preamble are supplied some other way than by - copying lines from source files. Second, a generated file might - contain material from several source files. Both make it impossible - to predict what line number an extracted file would have in the - generated file, so instead the algorithm for computing the line - number map looks for a block of lines in the fromtext which - matches what can be extracted from the source. This matching is - affected by the following options:

-matching mode

How equal must two lines be in order to match? The supported - modes are:

exact: Lines must be equal as strings. This is the default.
anyspace: All sequences of whitespace characters are converted to single - spaces before comparing.
nonspace: Only non-whitespace characters are considered when comparing.
none: Any two lines are considered to be equal.

-metaprefix string

The -metaprefix value to use when extracting. Defaults - to "%%", but for Tcl code it is more likely that "#" or "##" had - been used for the generated file.

-trimlines boolean

The -trimlines value to use when extracting. Defaults to - true.

The return value is in the form of a unified diff, containing only - those hunks which were not applied or were only partially applied; - a comment in the header of each hunk specifies which case is at - hand. It is normally necessary to manually review both the return - value from patch and the patched text itself, as this command - cannot adjust comment lines to match new content.

An example use would look like

-set sourceL [split [docstrip::util::thefile from.dtx] \n]
-set terminals {foo bar baz}
-set fromtext [docstrip::util::thefile from.tcl]
-set difftext [exec diff --unified from.tcl to.tcl]
-set leftover [docstrip::util::patch sourceL $terminals $fromtext\
-  [docstrip::util::import_unidiff $difftext] -metaprefix {#}]
-set F [open to.dtx w]; puts $F [join $sourceL \n]; close $F
-return $leftover
-

Here, "from.dtx" was used as source for "from.tcl", which - someone modified into "to.tcl". We're trying to construct a - "to.dtx" which can be used as source for "to.tcl".

docstrip::util::thefile filename ?option value ...?

The thefile command opens the file filename, reads it to - end, closes it, and returns the contents (dropping a final newline - if there is one). The option-value pairs are - passed on to fconfigure to configure the open file channel - before anything is read from it.

docstrip::util::import_unidiff diff-text ?warning-var?

This command parses a unified (diff flags -U and - --unified) format diff into the list-of-hunks format - expected by docstrip::util::patch. The diff-text - argument is the text to parse and the warning-var is, if - specified, the name in the calling context of a variable to which - any warnings about parsing problems will be appended.

The return value is a list of hunks. Each hunk is a list of - five elements "start1 end1 start2 end2 - lines". start1 and end1 are line numbers in the - "from" file of the first and last respectively lines of the hunk. - start2 and end2 are the corresponding line numbers in - the "to" file. Line numbers start at 1. The lines is a list - with two elements for each line in the hunk; the first specifies the - type of a line and the second is the actual line contents. The type - is - for lines only in the "from" file, + for lines - that are only in the "to" file, and 0 for lines that are - in both.

Keywords

.ddt, .dtx, LaTeX, Tcl module, catalogue, diff, docstrip, doctools, documentation, literate programming, module, package indexing, patch, source

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/changelog.html Index: embedded/www/tcllib/files/modules/doctools/changelog.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/changelog.html +++ /dev/null @@ -1,210 +0,0 @@ - -

- -

doctools::changelog(n) 1.1 tcllib "Documentation tools"

Name

doctools::changelog - Processing text in Emacs ChangeLog format

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require textutil
package require doctools::changelog ?1.1?

::doctools::changelog::scan text
::doctools::changelog::flatten entries
::doctools::changelog::toDoctools title module version entries
::doctools::changelog::merge entries...

Description

This package provides Tcl commands for the processing and reformatting -of text in the "ChangeLog" format generated by emacs.

API

::doctools::changelog::scan text

The command takes the text and parses it under the assumption -that it contains a ChangeLog as generated by emacs. It -returns a data structure describing the contents of this ChangeLog.

This data structure is a list where each element describes one entry -in the ChangeLog. Each element/entry is then a list of three elements -describing the date of the entry, its author, and the comments made, -in this order. The last item in each element/entry, the comments, is a -list of sections. Each section is described by a list containing two -elements, a list of file names, and a string containing the true -comment associated with the files of the section.

-    {
-	{
-	    date
-	    author
-	    {
-		{
-		    {file ...}
-		    commenttext
-		}
-		...
-	    }
-	}
-	{...}
-    }
-

::doctools::changelog::flatten entries

This command converts a list of entries as generated by -change::scan above into a simpler list of plain -text blocks each containing all the information of a -single entry.

::doctools::changelog::toDoctools title module version entries

This command converts the pre-parsed ChangeLog entries as -generated by the command ::doctools::changelog::scan into a -document in doctools format and returns it as the result of the -command.

The other three arguments supply the information for the header of -that document which is not available from the changelog itself.

::doctools::changelog::merge entries...

Each argument of the command is assumed to be a pre-parsed Changelog -as generated by the command ::doctools::changelog::scan. This -command merges all of them into a single structure, and collapses -multiple entries for the same date and author into a single entry. The -new structure is returned as the result of the command.

Bugs, Ideas, Feedback

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

Keywords

changelog, doctools, emacs

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/cvs.html Index: embedded/www/tcllib/files/modules/doctools/cvs.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/cvs.html +++ /dev/null @@ -1,207 +0,0 @@ - -

- -

doctools::cvs(n) 1 tcllib "Documentation tools"

Name

doctools::cvs - Processing text in 'cvs log' format

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require textutil
package require doctools::cvs ?1?

::doctools::cvs::scanLog text evar cvar fvar
::doctools::cvs::toChangeLog evar cvar fvar

Description

This package provides Tcl commands for the processing and reformatting -text in the format generated by the cvs log command.

The commands ::doctools::cvs::scanLog -and ::doctools::cvs::toChangeLog are derived from code found on -the Tcl'ers Wiki. See the references at the -end of the page.

API

::doctools::cvs::scanLog text evar cvar fvar

The command takes the text and parses it under the assumption -that it contains a CVS log as generated by cvs log. The -resulting information is stored in the variables whose names were -specified via evar, cvar, and fvar.

Already existing information in the referenced variables is preserved, -allowing the caller to merge data from multiple logs into one -database.

varname evar (in)

Has to refer to a scalar variable. After the call this variable will -contain a list of all the entries found in the log file. An entry is -identified through the combination of date and author, and can be -split over multiple physical entries, one per touched file.

It should be noted that the entries are listed in the same order as -they were found in the text. This is not necessarily sorted by -date or author.

Each item in the list is a list containing two elements, the date of -the entry, and its author, in this order. The date is formatted as -year/month/day.

varname cvar (in)

Has to refer to an array variable. Keys are strings containing the -date and author of log entries, in this order, separated by a comma.

The values are lists of comments made for the entry.

varname fvar (in)

Has to refer to an array variable. Keys are strings containing -date, author of a log entry, and a comment for that entry, in this -order, separated by commas.

The values are lists of the files the entry is touching.

::doctools::cvs::toChangeLog evar cvar fvar

The three arguments for this command are the same as the last three -arguments of the command ::doctools::cvs::scanLog. This command -however expects them to be filled with information about one or more -logs. It takes this information and converts it into a text in the -format of a ChangeLog as accepted and generated by emacs. The -constructed text is returned as the result of the command.

Bugs, Ideas, Feedback

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

Keywords

changelog, cvs, cvs log, emacs, log

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/docidx.html Index: embedded/www/tcllib/files/modules/doctools/docidx.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx.html +++ /dev/null @@ -1,413 +0,0 @@ - -

- -

doctools::idx(n) 1.0.8 tcllib "Documentation tools"

Name

doctools::idx - docidx - Processing indices

Table Of Contents
Synopsis
Description
PUBLIC API -
- PACKAGE COMMANDS
- OBJECT COMMAND
- OBJECT METHODS
- OBJECT CONFIGURATION
- FORMAT MAPPING
-
PREDEFINED ENGINES
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require doctools::idx ?1.0.8?

::doctools::idx::new objectName ?-option value ...?
::doctools::idx::help
::doctools::idx::search path
objectName method ?arg arg ...?
objectName configure
objectName configure option
objectName configure -option value...
objectName cget -option
objectName destroy
objectName format text
objectName map symbolic actual
objectName parameters
objectName search path
objectName setparam name value
objectName warnings

Description

This package provides a class for the creation of objects able to -process and convert text written in the docidx markup language -into any output format X for which a formatting engine is -available.

A reader interested in the markup language itself should start with -the docidx language introduction and proceed from there to -the formal specifications, i.e. the docidx language syntax -and the docidx language command reference.

If on the other hand the reader wishes to write her own formatting -engine for some format, i.e. is a plugin writer then reading -and understanding the docidx plugin API reference is an -absolute necessity, as that document specifies the interaction between -this package and its plugins, i.e. the formatting engines, in detail.

PUBLIC API

PACKAGE COMMANDS

::doctools::idx::new objectName ?-option value ...?

This command creates a new docidx object with an associated Tcl -command whose name is objectName. This object command is -explained in full detail in the sections OBJECT COMMAND -and OBJECT METHODS. The object command will be created -under the current namespace if the objectName is not fully -qualified, and in the specified namespace otherwise.

The options and their values coming after the name of the object are -used to set the initial configuration of the object.

::doctools::idx::help

This is a convenience command for applications wishing to provide -their user with a short description of the available formatting -commands and their meanings. It returns a string containing a standard -help text.

::doctools::idx::search path

Whenever an object created by this the package has to map the name of -a format to the file containing the code for its formatting engine it -will search for the file in a number of directories stored in a -list. See section FORMAT MAPPING for more explanations.

This list not only contains three default directories which are -declared by the package itself, but is also extensible user of the -package. -This command is the means to do so. When given a path to an -existing and readable directory it will prepend that directory to the -list of directories to search. This means that the path added -last is later searched through first.

An error will be thrown if the path either does not exist, is -not a directory, or is not readable.

OBJECT COMMAND

All commands created by ::doctools::idx::new have the following -general form and may be used to invoke various operations on their -docidx converter object.

objectName method ?arg arg ...?: The method method and its arg'uments determine the exact -behavior of the command. See section OBJECT METHODS for -the detailed specifications.

OBJECT METHODS

objectName configure

The method returns a list of all known options and their current -values when called without any arguments.

objectName configure option

The method behaves like the method cget when called with a -single argument and returns the value of the option specified by said -argument.

objectName configure -option value...

The method reconfigures the specified options of the object, -setting them to the associated values, when called with an even -number of arguments, at least two.

The legal options are described in the section -OBJECT CONFIGURATION.

objectName cget -option

This method expects a legal configuration option as argument and will -return the current value of that option for the object the method was -invoked for.

The legal configuration options are described in section -OBJECT CONFIGURATION.

objectName destroy

This method destroys the object it is invoked for.

objectName format text

This method runs the text through the configured formatting -engine and returns the generated string as its result. An error will -be thrown if no -format was configured for the object.

The method assumes that the text is in docidx format as -specified in the companion document docidx_fmt. Errors will be -thrown otherwise.

objectName map symbolic actual

This methods add one entry to the per-object mapping from -symbolic filenames to the actual uris. -The object just stores this mapping and makes it available to the -configured formatting engine through the command dt_fmap. -This command is described in more detail in the -docidx plugin API reference which specifies the interaction -between the objects created by this package and index formatting -engines.

objectName parameters

This method returns a list containing the names of all engine -parameters provided by the configured formatting engine. It will -return an empty list if the object is not yet configured for a -specific format.

objectName search path

This method extends the per-object list of paths searched for index -formatting engines. See also the command ::doctools::idx::search -on how to extend the per-package list of paths. Note that the path -entered last will be searched first. -For more details see section FORMAT MAPPING.

objectName setparam name value

This method sets the named engine parameter to the specified -value. -It will throw an error if the object is either not yet configured for -a specific format, or if the formatting engine for the configured -format does not provide a parameter with the given name. -The list of parameters provided by the configured formatting engine -can be retrieved through the method parameters.

objectName warnings

This method returns a list containing all the warnings which were -generated by the configured formatting engine during the last -invocation of the method format.

OBJECT CONFIGURATION

All docidx objects understand the following configuration options:

-file file

The argument of this option is stored in the object and made available -to the configured formatting engine through the command dt_file. -This command is described in more detail in the companion document -docidx_api which specifies the API between the object and -formatting engines.

The default value of this option is the empty string.

The configured formatting engine should interpret the value as the -name of the file containing the document which is currently processed.

-format text

The argument of this option specifies the format to generate and by -implication the formatting engine to use when converting text via the -method format. Its default value is the empty string. The -method format cannot be used if this option is not set to a -valid value at least once.

The package will immediately try to map the given name to a file -containing the code for a formatting engine generating that format. An -error will be thrown if this mapping fails. In that case a previously -configured format is left untouched.

The section FORMAT MAPPING explains in detail how the -package and object will look for engine implementations.

FORMAT MAPPING

The package and object will perform the following algorithm when -trying to map a format name foo to a file containing an -implementation of a formatting engine for foo:

If foo is the name of an existing file then this file is -directly taken as the implementation.
If not, the list of per-object search paths is searched. For each -directory in the list the package checks if that directory contains a -file "idx.foo". If yes, then that file is taken as the -implementation.
-
Note that this list of paths is initially empty and can be extended -through the object method search.
If not, the list of package paths is searched. -For each directory in the list the package checks if that directory -contains a file "idx.foo". If yes, then that file is taken -as the implementation.
-
This list of paths can be extended -through the command ::doctools::idx::search. -It contains initially one path, the subdirectory "mpformats" of -the directory the package itself is located in. In other words, if the -package implementation "docidx.tcl" is installed in the directory -"/usr/local/lib/tcllib/doctools" then it will by default search -the directory "/usr/local/lib/tcllib/doctools/mpformats" for -format implementations.
The mapping fails.

PREDEFINED ENGINES

The package provides predefined formatting engines for the following -formats. Some of the formatting engines support engine -parameters. These will be explicitly highlighted.

html

This engine generates HTML markup, for processing by web browsers and -the like. This engine supports three parameters:

footer

The value for this parameter has to be valid selfcontained HTML markup -for the body section of a HTML document. The default value is the -empty string. The value is inserted into the generated output just -before the </body> tag, closing the body of the generated -HTML.

This can be used to insert boilerplate footer markup into the -generated document.

header

The value for this parameter has to be valid selfcontained HTML markup -for the body section of a HTML document. The default value is the -empty string. The value is inserted into the generated output just -after the <body> tag, starting the body of the generated HTML.

This can be used to insert boilerplate header markup into the -generated document.

meta

The value for this parameter has to be valid selfcontained HTML markup -for the header section of a HTML document. The default value is the -empty string. The value is inserted into the generated output just -after the <head> tag, starting the header section of the -generated HTML.

This can be used to insert boilerplate meta data markup into the -generated document, like references to a stylesheet, standard meta -keywords, etc.

latex

This engine generates output suitable for the latex text -processor coming out of the TeX world.

list

This engine retrieves version, section and title of the manpage from -the document. As such it can be used to generate a directory listing -for a set of manpages.

nroff

This engine generates nroff output, for processing by nroff, -or groff. The result will be standard man pages as they are -known in the unix world.

null

This engine generates no outout at all. This can be used if one just -wants to validate some input.

tmml

This engine generates TMML markup as specified by Joe English. The Tcl -Manpage Markup Language is a derivate of XML.

wiki

This engine generates Wiki markup as understood by Jean Claude -Wippler's wikit application.

Bugs, Ideas, Feedback

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

Keywords

HTML, TMML, conversion, docidx, documentation, index, keyword index, latex, manpage, markup, nroff, wiki

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/docidx_intro.html Index: embedded/www/tcllib/files/modules/doctools/docidx_intro.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx_intro.html +++ /dev/null @@ -1,196 +0,0 @@ - -

- -

docidx_intro(n) 1.0 tcllib "Documentation tools"

Name

docidx_intro - docidx introduction

Table Of Contents
Description
RELATED FORMATS
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

docidx (short for documentation tables of contents) -stands for a set of related, yet different, entities which are working -together for the easy creation and transformation of keyword-based -indices for documentation. These are

A tcl based language for the semantic markup of a keyword index. -Markup is represented by Tcl commands.
A package providing the ability to read and transform texts written in -that markup language. It is important to note that the actual -transformation of the input text is delegated to plugins.
An API describing the interface between the package above and a -plugin.

Which of the more detailed documents are relevant to the reader of -this introduction depends on their role in the documentation process.

A writer of documentation has to understand the markup language -itself. A beginner to docidx should read the more informally written -docidx language introduction first. Having digested this -the formal docidx language syntax specification should -become understandable. A writer experienced with docidx may only -need the docidx language command reference from time to -time to refresh her memory.
-
While a document is written the dtp application can be used -to validate it, and after completion it also performs the conversion -into the chosen system of visual markup, be it *roff, HTML, plain -text, wiki, etc. The simpler dtplite application makes -internal use of docidx when handling directories of documentation, -automatically generating a proper keyword index for them.
A processor of documentation written in the docidx -markup language has to know which tools are available for use.
-
The main tool is the aforementioned dtp application provided -by Tcllib. The simpler dtplite does not expose docidx to the -user. -At the bottom level, common to both applications, however sits the -package doctoools::idx, providing the basic facilities to -read and process files containing text in the docidx format.
At last, but not least, plugin writers have to understand the -interaction between the doctools::idx package and its -plugins, as described in the docidx plugin API reference.

RELATED FORMATS

docidx does not stand alone, it has two companion formats. These are -called doctoc and doctools, and they are for the markup -of tables of contents, and general documentation, -respectively. -They are described in their own sets of documents, starting at the -doctoc introduction and the doctools introduction, -respectively.

Bugs, Ideas, Feedback

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

Keywords

index, keyword index, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/docidx_lang_cmdref.html Index: embedded/www/tcllib/files/modules/doctools/docidx_lang_cmdref.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx_lang_cmdref.html +++ /dev/null @@ -1,227 +0,0 @@ - -

- -

docidx_lang_cmdref(n) 1.0 tcllib "Documentation tools"

Name

docidx_lang_cmdref - docidx language command reference

Table Of Contents
Synopsis
Description
Commands
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

comment plaintext
include filename
index_begin text title
index_end
key text
lb
manpage file text
rb
url url label
vset varname value
vset varname

Description

This document specifies both names and syntax of all the commands -which together are the docidx markup language, version 1. -As this document is intended to be a reference the commands are listed -in alphabetical order, and the descriptions are relatively short. -A beginner should read the much more informally written -docidx language introduction first.

Commands

comment plaintext

Index markup. The argument text is marked up as a comment standing -outside of the actual text of the document. Main use is in free-form -text.

include filename

Templating. The contents of the named file are interpreted as text -written in the docidx markup and processed in the place of the -include command. The markup in the file has to be self-contained. It -is not possible for a markup command to cross the file boundaries.

index_begin text title

Document structure. The command to start an index. The arguments are a -label for the whole group of documents the index refers to -(text) and the overall title text for the index (title), -without markup.

The label often is the name of the package (or extension) the -documents belong to.

index_end

Document structure. Command to end an index. Anything in the document -coming after this command is in error.

key text

Index structure. This command adds the keyword text to the -index.

lb

Text. The command is replaced with a left bracket. Use in free-form -text. Required to avoid interpretation of a left bracket as the start -of a markup command. Its usage is restricted to the arguments of other -markup commands.

manpage file text

Index structure. This command adds an element to the index which -refers to a document. The document is specified through the symbolic -name file. The text argument is used to label the -reference.

Symbolic names are used to preserve the convertibility of this format -to any output format. The actual name of the file will be inserted by -the chosen formatting engine when converting the input. This will be -based on a mapping from symbolic to actual names given to the engine.

rb

Text. The command is replaced with a right bracket. Use in free-form -text. Required to avoid interpretation of a right bracket as the end -of a markup command. Its usage is restricted to the arguments of other -commands.

url url label

Index structure. This is the second command to add an element to the -index. To refer to a document it is not using a symbolic name however, -but a (possibly format-specific) url describing the exact location of -the document indexed here.

vset varname value

Templating. In this form the command sets the named document variable -to the specified value. It does not generate output. I.e. the -command is replaced by the empty string.

vset varname

Templating. In this form the command is replaced by the value of the -named document variable

Bugs, Ideas, Feedback

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

Keywords

docidx commands, docidx language, docidx markup, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/docidx_lang_faq.html Index: embedded/www/tcllib/files/modules/doctools/docidx_lang_faq.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx_lang_faq.html +++ /dev/null @@ -1,184 +0,0 @@ - -

- -

docidx_lang_faq(n) 1.0 tcllib "Documentation tools"

Name

docidx_lang_faq - docidx language faq

Table Of Contents
Description
OVERVIEW -
- What is this document?
-
EXAMPLES -
- Where do I find docidx examples?
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

OVERVIEW

What is this document?

This document is currently mainly a placeholder, to be filled with -commonly asked questions about the docidx markup language -and companions, and their answers.

Please report any questions (and, if possible, answers) we should -consider for this document as explained in the section -Bugs, Ideas, Feedback below.

EXAMPLES

Where do I find docidx examples?

We have no direct examples of documents written using docidx -markup. However the doctools processor dtplite does generate -a table of contents when processing a set of documents written in -doctools markup. The intermediate file for it uses docidx -markup and is not deleted when generation completes. Such files can -therefore serve as examples.

dtplite is distributed as part of Tcllib, so to get it you -need one of

A snapshot of Tcllib. How to retrieve such a snapshot and the -tools required for this are described at -Development Snapshots
A Tcllib release archive. They are available at the home -page.

Bugs, Ideas, Feedback

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

Keywords

docidx commands, docidx language, docidx markup, docidx syntax, examples, faq, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/docidx_lang_intro.html Index: embedded/www/tcllib/files/modules/doctools/docidx_lang_intro.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx_lang_intro.html +++ /dev/null @@ -1,294 +0,0 @@ - -

- -

docidx_lang_intro(n) 1.0 tcllib "Documentation tools"

Name

docidx_lang_intro - docidx language introduction

Table Of Contents
Description -
- Fundamentals
- Basic structure
- Advanced structure
- Escapes
-
FURTHER READING
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

This document is an informal introduction to version 1 of the docidx -markup language based on a multitude of examples. After reading this a -writer should be ready to understand the two parts of the formal -specification, i.e. the docidx language syntax specification -and the docidx language command reference.

Fundamentals

While the docidx markup language is quite similar to the -doctools markup language, in the broadest terms possible, -there is one key difference. An index consists essentially only of -markup commands, with no plain text interspersed between them, except -for whitespace.

Each markup command is a Tcl command surrounded by a matching pair of -[ and ]. Inside of these delimiters the usual -rules for a Tcl command apply with regard to word quotation, nested -commands, continuation lines, etc. I.e.

-    ... [key {markup language}] ...
-

-  ... [manpage thefile \\
-          {file description}] ...
-

Basic structure

The most simple document which can be written in docidx is

-    [index_begin GROUPTITLE TITLE]
-    [index_end]
-

Not very useful, but valid. This also shows us that all docidx -documents consist of only one part where we will list all keys and -their references.

A more useful index will contain at least keywords, or short 'keys', -i.e. the phrases which were indexed. So:

-[index_begin GROUPTITLE TITLE]
-[key markup]
-[key {semantic markup}]]
-[key {docidx markup}]
-[key {docidx language}]
-[key {docidx commands}]
-[index_end]
-

In the above example the command key is used to declare the -keyword phrases we wish to be part of the index.

However a truly useful index does not only list the keyword phrases, -but will also contain references to documents associated with the -keywords. Here is a made-up index for all the manpages in the module -base64:

-[index_begin tcllib/base64 {De- & Encoding}]
-[key base64]
-[manpage base64]
-[key encoding]
-[manpage base64]
-[manpage uuencode]
-[manpage yencode]
-[key uuencode]
-[manpage uuencode]
-[key yEnc]
-[manpage yencode]
-[key ydecode]
-[manpage yencode]
-[key yencode]
-[manpage yencode]
-[index_end]
-

In the above example the command manpage is used to insert -references to documents, using symbolic file names, with each command -belonging to the last key command coming before it.

The other command to insert references is url. In contrast to -manpage it uses explicit (possibly format-specific) urls to -describe the location of the referenced document. As such this command -is intended for the creation of references to external documents which -could not be handled in any other way.

Advanced structure

In all previous examples we fudged a bit regarding the markup actually -allowed to be used before the index_begin command opening the -document.

Instead of only whitespace the two templating commands include -and vset are also allowed, to enable the writer to either set -and/or import configuration settings relevant to the table of -contents. I.e. it is possible to write

-[include FILE]
-[vset VAR VALUE]
-[index_begin GROUPTITLE TITLE]
-...
-[index_end]
-

Even more important, these two commands are allowed anywhere where a -markup command is allowed, without regard for any other -structure.

-[index_begin GROUPTITLE TITLE]
-[include FILE]
-[vset VAR VALUE]
-...
-[index_end]
-

The only restriction include has to obey is that the contents of -the included file must be valid at the place of the inclusion. I.e. a -file included before index_begin may contain only the templating -commands vset and include, a file included after a key -may contain only manape or url references, and other keys, etc.

Escapes

Beyond the 6 commands shown so far we have two more available. -However their function is not the marking up of index structure, but -the insertion of characters, namely [ and ]. -These commands, lb and rb respectively, are required -because our use of [ and ] to bracket markup commands makes it -impossible to directly use [ and ] within the text.

Our example of their use are the sources of the last sentence in the -previous paragraph, with some highlighting added.

-  ...
-  These commands, [cmd lb] and [cmd lb] respectively, are required
-  because our use of [lb] and [rb] to bracket markup commands makes it
-  impossible to directly use [lb] and [rb] within the text.
-  ...
-

Bugs, Ideas, Feedback

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

Keywords

docidx commands, docidx language, docidx markup, docidx syntax, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/docidx_lang_syntax.html Index: embedded/www/tcllib/files/modules/doctools/docidx_lang_syntax.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx_lang_syntax.html +++ /dev/null @@ -1,214 +0,0 @@ - -

- -

docidx_lang_syntax(n) 1.0 tcllib "Documentation tools"

Name

docidx_lang_syntax - docidx language syntax

Table Of Contents
Description
Fundamentals
Lexical definitions
Syntax
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

This document contains the formal specification of the syntax of the -docidx markup language, version 1 in Backus-Naur-Form. This document -is intended to be a reference, complementing the -docidx language command reference. -A beginner should read the much more informally written -docidx language introduction first before trying to -understand either this document or the command reference.

Fundamentals

In the broadest terms possible the docidx markup language is -like SGML and similar languages. A document written in this language -consists primarily of markup commands, with text embedded into it at -some places.

Each markup command is a just Tcl command surrounded by a matching -pair of [ and ]. Which commands are available, -and their arguments, i.e. syntax is specified in the -docidx language command reference.

In this document we specify first the lexeme, and then the syntax, -i.e. how we can mix text and markup commands with each other.

Lexical definitions

In the syntax rules listed in the next section

<TEXT> stands for all text except markup commands.
Any XXX stands for the markup command [xxx] including its -arguments. Each markup command is a Tcl command surrounded by a -matching pair of [ and ]. Inside of these -delimiters the usual rules for a Tcl command apply with regard to word -quotation, nested commands, continuation lines, etc.
<WHITE> stands for all text consisting only of spaces, newlines, -tabulators and the comment markup command.

Syntax

The rules listed here specify only the syntax of docidx documents. The -lexical level of the language was covered in the previous section.

Regarding the syntax of the (E)BNF itself

The construct { X } stands for zero or more occurrences of X.
The construct [ X ] stands for zero or one occurrence of X.

The syntax:

-index     = defs
-            INDEX_BEGIN
-            [ contents ]
-            INDEX_END
-            { <WHITE> }
-defs      = { INCLUDE | VSET | <WHITE> }
-contents  = keyword { keyword }
-keyword   = defs KEY ref { ref }
-ref       = MANPAGE | URL | defs
-

At last a rule we were unable to capture in the EBNF syntax, as it is -about the arguments of the markup commands, something which is not -modeled here.

The arguments of all markup commands have to be plain text, and/or text -markup commands, i.e. one of
-
1. lb,
2. rb, or
3. vset (1-argument form).
-

Bugs, Ideas, Feedback

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

Keywords

docidx commands, docidx language, docidx markup, docidx syntax, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/docidx_plugin_apiref.html Index: embedded/www/tcllib/files/modules/doctools/docidx_plugin_apiref.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx_plugin_apiref.html +++ /dev/null @@ -1,443 +0,0 @@ - -

- -

docidx_plugin_apiref(n) 1.0 tcllib "Documentation tools"

Name

docidx_plugin_apiref - docidx plugin API reference

Table Of Contents
Synopsis
Description
OVERVIEW
FRONTEND COMMANDS
PLUGIN COMMANDS -
- Management commands
- Formatting commands
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

- -

Description

This document is intended for plugin writers, i.e. developers -wishing to write an index formatting engine for some output -format X.

It specifies the interaction between the doctools::idx -package and its plugins, i.e. the interface any index formatting -engine has to comply with.

This document deals with version 1 of the interface.

A reader who is on the other hand more interested in the markup -language itself should start with the -docidx language introduction and proceed from there to the -formal specifications, i.e. the docidx language syntax and -the docidx language command reference.

OVERVIEW

The API for an index formatting engine consists of two major sections.

On the one side we have a set of commands through which the plugin is -able to query the frontend. These commands are provided by the -frontend and linked into the plugin interpreter. Please see section -FRONTEND COMMANDS for their detailed specification.

And on the other side the plugin has to provide its own set of -commands which will then be called by the frontend in a specific -sequence while processing input. They, again, fall into two -categories, management and formatting. -Please see section PLUGIN COMMANDS and its subsections for -their detailed specification.

FRONTEND COMMANDS

This section specifies the set of commands through which a plugin, -also known as an index formatting engine, is able to query the -frontend. These commands are provided by the frontend and linked into -the plugin interpreter.

I.e. an index formatting engine can assume that all of the following -commands are present when any of its own commands (as specified in -section PLUGIN COMMANDS) are executed.

Beyond that it can also assume that it has full access to its own safe -interpreter and thus is not able to damage the other parts of the -processor, nor can it damage the filesystem. -It is however able to either kill or hang the whole process, by -exiting, or running an infinite loop.

Coming back to the imported commands, all the commands with prefix -dt_ provide limited access to specific parts of the frontend, -whereas the commands with prefix ex_ provide access to the -state of the textutil::expander object which does the main -parsing of the input within the frontend. These commands should not be -except under very special circumstances.

dt_fmap symfname

Query command. It returns the actual pathname to use in the output in -place of the symbolic filename symfname. It will return the -unchanged input if no mapping was established for symfname.

The required mappings are established with the method map of -a frontend, as explained in section OBJECT METHODS -of the documentation for the package doctools::idx.

dt_format

Query command. It returns the name of the format associated with the -index formatting engine.

dt_read file

Controlled filesystem access. Returns contents of file for -whatever use desired by the plugin. -Only files which are either in the same directory as the file -containing the engine, or below it, can be loaded. Trying to load a -file outside of this directory causes an error.

dt_source file

Controlled filesystem access. This command allows the index formatting -engine to load additional Tcl code it may need. -Only files which are either in the same directory as the file -containing the engine, or below it, can be loaded. Trying to load a -file outside of this directory causes an error.

ex_cappend text

Appends a string to the output in the current context. This command -should rarely be used by macros or application code.

ex_cget varname

Retrieves the value of variable varname, defined in the current -context.

ex_cis cname

Determines whether or not the name of the current context is -cname.

ex_cname

Returns the name of the current context.

ex_cpop cname

Pops a context from the context stack, returning all accumulated -output in that context. The context must be named cname, or an -error results.

ex_cpush cname

Pushes a context named cname onto the context stack. The -context must be popped by cpop before expansion ends or an -error results.

ex_cset varname value

Sets variable varname to value in the current context.

ex_lb ?newbracket?

Returns the current value of the left macro expansion bracket; this is -for use as or within a macro, when the bracket needs to be included in -the output text. If newbracket is specified, it becomes the new -bracket, and is returned.

ex_rb ?newbracket?

Returns the current value of the right macro expansion bracket; this -is for use as or within a macro, when the bracket needs to be included -in the output text. If newbracket is specified, it becomes the -new bracket, and is returned.

PLUGIN COMMANDS

The plugin has to provide its own set of commands which will then be -called by the frontend in a specific sequence while processing -input. They fall into two categories, management and formatting. Their -expected names, signatures, and responsibilities are specified in the -following two subsections.

Management commands

The management commands a plugin has to provide are used by the -frontend to

initialize and shutdown the plugin
determine the number of passes it has - to make over the input
initialize and shutdown each pass
query and initialize engine parameters

After the plugin has been loaded and the frontend commands are -established the commands will be called in the following sequence:

-    idx_numpasses -> n
-    idx_listvariables -> vars
-    idx_varset var1 value1
-    idx_varset var2 value2
-    ...
-    idx_varset varK valueK
-    idx_initialize
-    idx_setup 1
-    ...
-    idx_setup 2
-    ...
-    ...
-    idx_setup n
-    ...
-    idx_postprocess
-    idx_shutdown
-    ...
-

I.e. first the number of passes and the set of available engine -parameters is established, followed by calls setting the -parameters. That second part is optional.

After that the plugin is initialized, the specified number of passes -executed, the final result run through a global post processing step -and at last the plugin is shutdown again. This can be followed by more -conversions, restarting the sequence at idx_varset.

In each of the passes, i.e. after the calls of idx_setup the -frontend will process the input and call the formatting commands as -markup is encountered. This means that the sequence of formatting -commands is determined by the grammar of the docidx markup language, -as specified in the docidx language syntax specification.

A different way of looking at the sequence is:

First some basic parameters are determined.
Then everything starting at the first idx_varset to -idx_shutdown forms a run, the formatting of a -single input. Each run can be followed by more.
Embedded within each run we have one or more passes, -each starting with idx_setup and going until either the next -idx_setup or idx_postprocess is reached.
-
If more than one pass is required to perform the formatting only the -output of the last pass is relevant. The output of all the previous, -preparatory passes is ignored.

The commands, their names, signatures, and responsibilities are, in -detail:

idx_initialize

Initialization/Shutdown. -This command is called at the beginning of every conversion run, as -the first command of that run. Note that a run is not a pass, but may -consist of multiple passes. -It has to initialize the general state of the plugin, beyond the -initialization done during the load. No return value is expected, and -any returned value is ignored.

idx_listvariables

Initialization/Shutdown and Engine parameters. -Second command is called after the plugin code has been loaded, -i.e. immediately after idx_numpasses. -It has to return a list containing the names of the parameters the -frontend can set to configure the engine. This list can be empty.

idx_numpasses

Initialization/Shutdown and Pass management. -First command called after the plugin code has been loaded. No other -command of the engine will be called before it. -It has to return the number of passes this engine requires to fully -process the input document. This value has to be an integer number -greater or equal to one.

idx_postprocess text

Initialization/Shutdown. -This command is called immediately after the last pass in a run. Its -argument is the result of the conversion generated by that pass. It is -provided to allow the engine to perform any global modifications of -the generated document. If no post-processing is required for a -specific format the command has to just return the argument.

Expected to return a value, the final result of formatting the input.

idx_setup n

Initialization/Shutdown and Pass management. -This command is called at the beginning of each pass over the input in -a run. Its argument is the number of the pass which has begun. Passes -are counted from 1 upward. -The command has to set up the internal state of the plugin for this -particular pass. No return value is expected, and any returned value -is ignored.

idx_shutdown

Initialization/Shutdown. -This command is called at the end of every conversion run. It is the -last command called in a run. It has to clean up of all the -run-specific state in the plugin. -After the call the engine has to be in a state which allows the -initiation of another run without fear that information from the last -run is leaked into this new run. -No return value is expected, and any returned value is ignored.

idx_varset varname text

Engine parameters. -This command is called by the frontend to set an engine parameter to a -particular value. -The parameter to change is specified by varname, the value to -set in text.

The command has to throw an error if an unknown varname is -used. Only the names returned by idx_listvariables have to be -considered as known.

The values of all engine parameters have to persist between passes and -runs.

Formatting commands

The formatting commands have to implement the formatting for the -output format, for all the markup commands of the docidx markup -language, except lb, rb, vset, include, and -comment. These exceptions are processed by the frontend and are -never seen by the plugin. In return a command for the formatting of -plain text has to be provided, something which has no markup in the -input at all.

This means, that each of the five markup commands specified in the -docidx language command reference and outside of the set of -exceptions listed above has an equivalent formatting command which -takes the same arguments as the markup command and whose name is the -name of markup command with the prefix fmt_ added to it.

All commands are expected to format their input in some way per the -semantics specified in the command reference and to return whatever -part of this that they deem necessary as their result, which will be -added to the output.

To avoid essentially duplicating the command reference we do not list -any of the command here and simply refer the reader to the -docidx language command reference for their signature and -description. The sole exception is the plain text formatter, which has -no equivalent markup command.

The calling sequence of formatting commands is not as rigid as for the -management commands, but determined by the grammar of the docidx -markup language, as specified in the docidx language syntax -specification.

fmt_plain_text text

No associated markup command.

Called by the frontend for any plain text encountered in the -input. It has to perform any and all special processing required for -plain text.

The formatted text is expected as the result of the command, -and added to the output. If no special processing is required it has -to simply return its argument without change.

Bugs, Ideas, Feedback

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

Keywords

formatting engine, index, index formatter, keywords, markup, plugin, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctoc.html Index: embedded/www/tcllib/files/modules/doctools/doctoc.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc.html +++ /dev/null @@ -1,413 +0,0 @@ - -

- -

doctools::toc(n) 1.1.7 tcllib "Documentation tools"

Name

doctools::toc - doctoc - Processing tables of contents

Table Of Contents
Synopsis
Description
PUBLIC API -
- PACKAGE COMMANDS
- OBJECT COMMAND
- OBJECT METHODS
- OBJECT CONFIGURATION
- FORMAT MAPPING
-
PREDEFINED ENGINES
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require doctools::toc ?1.1.7?

::doctools::toc::new objectName ?-option value ...?
::doctools::toc::help
::doctools::toc::search path
objectName method ?arg arg ...?
objectName configure
objectName configure option
objectName configure -option value...
objectName cget -option
objectName destroy
objectName format text
objectName map symbolic actual
objectName parameters
objectName search path
objectName setparam name value
objectName warnings

Description

This package provides a class for the creation of objects able to -process and convert text written in the doctoc markup language -into any output format X for which a formatting engine is -available.

A reader interested in the markup language itself should start with -the doctoc language introduction and proceed from there to -the formal specifications, i.e. the doctoc language syntax -and the doctoc language command reference.

If on the other hand the reader wishes to write her own formatting -engine for some format, i.e. is a plugin writer then reading -and understanding the doctoc plugin API reference is an -absolute necessity, as that document specifies the interaction between -this package and its plugins, i.e. the formatting engines, in detail.

PUBLIC API

PACKAGE COMMANDS

::doctools::toc::new objectName ?-option value ...?

This command creates a new doctoc object with an associated Tcl -command whose name is objectName. This object command is -explained in full detail in the sections OBJECT COMMAND -and OBJECT METHODS. The object command will be created -under the current namespace if the objectName is not fully -qualified, and in the specified namespace otherwise.

The options and their values coming after the name of the object are -used to set the initial configuration of the object.

::doctools::toc::help

::doctools::toc::search path

An error will be thrown if the path either does not exist, is -not a directory, or is not readable.

OBJECT COMMAND

All commands created by ::doctools::toc::new have the following -general form and may be used to invoke various operations on their -doctoc converter object.

objectName method ?arg arg ...?: The method method and its arg'uments determine the exact -behavior of the command. See section OBJECT METHODS for -the detailed specifications.

OBJECT METHODS

objectName configure

The method returns a list of all known options and their current -values when called without any arguments.

objectName configure option

The method behaves like the method cget when called with a -single argument and returns the value of the option specified by said -argument.

objectName configure -option value...

The method reconfigures the specified options of the object, -setting them to the associated values, when called with an even -number of arguments, at least two.

The legal options are described in the section -OBJECT CONFIGURATION.

objectName cget -option

This method expects a legal configuration option as argument and will -return the current value of that option for the object the method was -invoked for.

The legal configuration options are described in section -OBJECT CONFIGURATION.

objectName destroy

This method destroys the object it is invoked for.

objectName format text

This method runs the text through the configured formatting -engine and returns the generated string as its result. An error will -be thrown if no -format was configured for the object.

The method assumes that the text is in doctoc format as -specified in the companion document doctoc_fmt. Errors will be -thrown otherwise.

objectName map symbolic actual

This methods add one entry to the per-object mapping from -symbolic filenames to the actual uris. -The object just stores this mapping and makes it available to the -configured formatting engine through the command dt_fmap. -This command is described in more detail in the -doctoc plugin API reference which specifies the interaction -between the objects created by this package and toc formatting -engines.

objectName parameters

objectName search path

This method extends the per-object list of paths searched for toc -formatting engines. See also the command ::doctools::toc::search -on how to extend the per-package list of paths. Note that the path -entered last will be searched first. -For more details see section FORMAT MAPPING.

objectName setparam name value

objectName warnings

This method returns a list containing all the warnings which were -generated by the configured formatting engine during the last -invocation of the method format.

OBJECT CONFIGURATION

All doctoc objects understand the following configuration options:

-file file

The argument of this option is stored in the object and made available -to the configured formatting engine through the command dt_file. -This command is described in more detail in the companion document -doctoc_api which specifies the API between the object and -formatting engines.

The default value of this option is the empty string.

The configured formatting engine should interpret the value as the -name of the file containing the document which is currently processed.

-format text

The section FORMAT MAPPING explains in detail how the -package and object will look for engine implementations.

FORMAT MAPPING

The package and object will perform the following algorithm when -trying to map a format name foo to a file containing an -implementation of a formatting engine for foo:

If foo is the name of an existing file then this file is -directly taken as the implementation.
If not, the list of per-object search paths is searched. For each -directory in the list the package checks if that directory contains a -file "toc.foo". If yes, then that file is taken as the -implementation.
-
Note that this list of paths is initially empty and can be extended -through the object method search.
If not, the list of package paths is searched. -For each directory in the list the package checks if that directory -contains a file "toc.foo". If yes, then that file is taken -as the implementation.
-
This list of paths can be extended -through the command ::doctools::toc::search. -It contains initially one path, the subdirectory "mpformats" of -the directory the package itself is located in. In other words, if the -package implementation "doctoc.tcl" is installed in the directory -"/usr/local/lib/tcllib/doctools" then it will by default search -the directory "/usr/local/lib/tcllib/doctools/mpformats" for -format implementations.
The mapping fails.

PREDEFINED ENGINES

The package provides predefined formatting engines for the following -formats. Some of the formatting engines support engine -parameters. These will be explicitly highlighted.

html

This engine generates HTML markup, for processing by web browsers and -the like. This engine supports three parameters:

footer

This can be used to insert boilerplate footer markup into the -generated document.

header

The value for this parameter has to be valid selfcontained HTML markup -for the body section of a HTML document. The default value is the -empty string. The value is inserted into the generated output just -after the <body> tag, starting the body of the generated HTML.

This can be used to insert boilerplate header markup into the -generated document.

meta

This can be used to insert boilerplate meta data markup into the -generated document, like references to a stylesheet, standard meta -keywords, etc.

latex

This engine generates output suitable for the latex text -processor coming out of the TeX world.

list

This engine retrieves version, section and title of the manpage from -the document. As such it can be used to generate a directory listing -for a set of manpages.

nroff

This engine generates nroff output, for processing by nroff, -or groff. The result will be standard man pages as they are -known in the unix world.

null

This engine generates no outout at all. This can be used if one just -wants to validate some input.

tmml

This engine generates TMML markup as specified by Joe English. The Tcl -Manpage Markup Language is a derivate of XML.

wiki

This engine generates Wiki markup as understood by Jean Claude -Wippler's wikit application.

Bugs, Ideas, Feedback

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

Keywords

HTML, TMML, conversion, doctoc, documentation, latex, manpage, markup, nroff, table of contents, toc, wiki

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctoc_intro.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_intro.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc_intro.html +++ /dev/null @@ -1,195 +0,0 @@ - -

- -

doctoc_intro(n) 1.0 tcllib "Documentation tools"

Name

doctoc_intro - doctoc introduction

Table Of Contents
Description
RELATED FORMATS
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

doctoc (short for documentation tables of contents) -stands for a set of related, yet different, entities which are working -together for the easy creation and transformation of tables of -contents for documentation. These are

A tcl based language for the semantic markup of a table of -contents. Markup is represented by Tcl commands.
A package providing the ability to read and transform texts written in -that markup language. It is important to note that the actual -transformation of the input text is delegated to plugins.
An API describing the interface between the package above and a -plugin.

Which of the more detailed documents are relevant to the reader of -this introduction depends on their role in the documentation process.

A writer of documentation has to understand the markup language -itself. A beginner to doctoc should read the more informally written -doctoc language introduction first. Having digested this -the formal doctoc language syntax specification should -become understandable. A writer experienced with doctoc may only -need the doctoc language command reference from time to -time to refresh her memory.
-
While a document is written the dtp application can be used -to validate it, and after completion it also performs the conversion -into the chosen system of visual markup, be it *roff, HTML, plain -text, wiki, etc. The simpler dtplite application makes -internal use of doctoc when handling directories of documentation, -automatically generating a proper table of contents for them.
A processor of documentation written in the doctoc -markup language has to know which tools are available for use.
-
The main tool is the aforementioned dtp application provided -by Tcllib. The simpler dtplite does not expose doctoc to the -user. -At the bottom level, common to both applications, however sits the -package doctoools::toc, providing the basic facilities to -read and process files containing text in the doctoc format.
At last, but not least, plugin writers have to understand the -interaction between the doctools::toc package and its -plugins, as described in the doctoc plugin API reference.

RELATED FORMATS

doctoc does not stand alone, it has two companion formats. These are -called docidx and doctools, and they are for the markup -of keyword indices, and general documentation, respectively. -They are described in their own sets of documents, starting at the -docidx introduction and the doctools introduction, -respectively.

Bugs, Ideas, Feedback

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

Keywords

markup, semantic markup, table of contents, toc

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctoc_lang_cmdref.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_lang_cmdref.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc_lang_cmdref.html +++ /dev/null @@ -1,232 +0,0 @@ - -

- -

doctoc_lang_cmdref(n) 1.0 tcllib "Documentation tools"

Name

doctoc_lang_cmdref - doctoc language command reference

Table Of Contents
Synopsis
Description
Commands
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

This document specifies both names and syntax of all the commands -which together are the doctoc markup language, version 1. -As this document is intended to be a reference the commands are listed -in alphabetical order, and the descriptions are relatively short. -A beginner should read the much more informally written -doctoc language introduction first.

Commands

comment plaintext

Toc markup. The argument text is marked up as a comment standing -outside of the actual text of the document. Main use is in free-form -text.

division_end

Toc structure. This command closes the division opened by the last -division_begin command coming before it, and not yet closed.

division_start text ?symfile?

Toc structure. This command opens a division in the table of -contents. Its counterpart is division_end. Together they allow a -user to give a table of contents additional structure.

The title of the new division is provided by the argument text.

If the symbolic filename symfile is present then the section -title should link to the referenced document, if links are supported -by the output format.

include filename

Templating. The contents of the named file are interpreted as text -written in the doctoc markup and processed in the place of the -include command. The markup in the file has to be self-contained. It -is not possible for a markup command to cross the file boundaries.

item file text desc

Toc structure. This command adds an individual element to the table of -contents. Each such element refers to a document. The document is -specified through the symbolic name file. The text -argument is used to label the reference, whereas the desc -provides a short descriptive text of that document.

The symbolic names are used to preserve the convertibility of this -format to any output format. The actual name of the file will be -inserted by the chosen formatting engine when converting the -input. This will be based on a mapping from symbolic to actual names -given to the engine.

lb

rb

toc_begin text title

Document structure. The command to start a table of contents. The -arguments are a label for the whole group of documents the index -refers to (text) and the overall title text for the index -(title), without markup.

The label often is the name of the package (or extension) the -documents belong to.

toc_end

Document structure. Command to end a table of contents. Anything in -the document coming after this command is in error.

vset varname value

Templating. In this form the command sets the named document variable -to the specified value. It does not generate output. I.e. the -command is replaced by the empty string.

vset varname

Templating. In this form the command is replaced by the value of the -named document variable

Bugs, Ideas, Feedback

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

Keywords

doctoc commands, doctoc language, doctoc markup, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctoc_lang_faq.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_lang_faq.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc_lang_faq.html +++ /dev/null @@ -1,184 +0,0 @@ - -

- -

doctoc_lang_faq(n) 1.0 tcllib "Documentation tools"

Name

doctoc_lang_faq - doctoc language faq

Table Of Contents
Description
OVERVIEW -
- What is this document?
-
EXAMPLES -
- Where do I find doctoc examples?
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

OVERVIEW

What is this document?

This document is currently mainly a placeholder, to be filled with -commonly asked questions about the doctoc markup language -and companions, and their answers.

Please report any questions (and, if possible, answers) we should -consider for this document as explained in the section -Bugs, Ideas, Feedback below.

EXAMPLES

Where do I find doctoc examples?

We have no direct examples of documents written using doctoc -markup. However the doctools processor dtplite does generate -a table of contents when processing a set of documents written in -doctools markup. The intermediate file for it uses doctoc -markup and is not deleted when generation completes. Such files can -therefore serve as examples.

dtplite is distributed as part of Tcllib, so to get it you -need one of

A snapshot of Tcllib. How to retrieve such a snapshot and the -tools required for this are described at -Development Snapshots
A Tcllib release archive. They are available at the home -page.

Bugs, Ideas, Feedback

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

Keywords

doctoc commands, doctoc language, doctoc markup, doctoc syntax, examples, faq, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctoc_lang_intro.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_lang_intro.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc_lang_intro.html +++ /dev/null @@ -1,359 +0,0 @@ - -

- -

doctoc_lang_intro(n) 1.0 tcllib "Documentation tools"

Name

doctoc_lang_intro - doctoc language introduction

Table Of Contents
Description -
- Fundamentals
- Basic structure
- Items
- Divisions
- Advanced structure
- Escapes
-
FURTHER READING
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

This document is an informal introduction to version 1.1 of the doctoc -markup language based on a multitude of examples. After reading this a -writer should be ready to understand the two parts of the formal -specification, i.e. the doctoc language syntax specification -and the doctoc language command reference.

Fundamentals

While the doctoc markup language is quite similar to the -doctools markup language, in the broadest terms possible, -there is one key difference. A table of contents consists essentially -only of markup commands, with no plain text interspersed between them, -except for whitespace.

-    ... [division_start {Appendix 1}] ...
-

-  ... [item thefile \\
-          label {file description}] ...
-

Basic structure

The most simple document which can be written in doctoc is

-    [toc_begin GROUPTITLE TITLE]
-    [toc_end]
-

This also shows us that all doctoc documents consist of only one -part where we will list items and divisions.

The user is free to mix these as she sees fit. This is a change from -version 1 of the language, which did not allow this mixing, but only -the use of either a series of items or a series of divisions.

We will discuss the commands for each of these two possibilities in -the next sections.

Items

Use the command item to put an item into a table of -contents. This is essentially a reference to a section, subsection, -etc. in the document, or set of documents, the table of contents is -for. The command takes three arguments, a symbolic name for the file -the item is for and two text to label the item and describe the -referenced section.

Symbolic names are used to preserve the convertibility of this format -to any output format. The actual name of any file will be inserted by -the chosen formatting engine when converting the input, based on a -mapping from symbolic to actual names given to the engine.

Here a made up example for a table of contents of this document:

-[toc_begin Doctoc {Language Introduction}]
-[item 1 DESCRIPTION]
-[item 1.1 {Basic structure}]
-[item 1.2 Items]
-[item 1.3 Divisions]
-[item 2 {FURTHER READING}]
-[toc_end]
-

Divisions

One thing of notice in the last example in the previous section is -that the referenced sections actually had a nested structure, -something which was expressed in the item labels, by using a common -prefix for all the sections nested under section 1.

This kind of structure can be made more explicit in the doctoc -language by using divisions. Instead of using a series of plain items -we use a series of divisions for the major references, and then place -the nested items inside of these.

Of course, instead of the nested items we can again use divisions and -thus nest arbitrarily deep.

A division is marked by two commands instead of one, one to start it, -the other to close the last opened division. They are:

division_start: This command opens a new division. It takes one or two arguments, the -title of the division, and the symbolic name of the file it refers -to. The latter is optional. -If the symbolic filename is present then the section title should link -to the referenced document, if links are supported by the output -format.
division_end: This command closes the last opened and not yet closed division.

Using this we can recast the last example like this

-[toc_begin Doctoc {Language Introduction}]
-[division_start DESCRIPTION]
-[item 1 {Basic structure}]
-[item 2 Items]
-[item 3 Divisions]
-[division_end]
-[division_start {FURTHER READING}]
-[division_end]
-[toc_end]
-

Or, to demonstrate deeper nesting

-[toc_begin Doctoc {Language Introduction}]
-[division_start DESCRIPTION]
-[division_start {Basic structure}]
-[item 1 Do]
-[item 2 Re]
-[division_end]
-[division_start Items]
-[item a Fi]
-[item b Fo]
-[item c Fa]
-[division_end]
-[division_start Divisions]
-[item 1 Sub]
-[item 1 Zero]
-[division_end]
-[division_end]
-[division_start {FURTHER READING}]
-[division_end]
-[toc_end]
-

And do not forget, it is possible to freely mix items and divisions, -and to have empty divisions.

-[toc_begin Doctoc {Language Introduction}]
-[item 1 Do]
-[division_start DESCRIPTION]
-[division_start {Basic structure}]
-[item 2 Re]
-[division_end]
-[item a Fi]
-[division_start Items]
-[item b Fo]
-[item c Fa]
-[division_end]
-[division_start Divisions]
-[division_end]
-[division_end]
-[division_start {FURTHER READING}]
-[division_end]
-[toc_end]
-

Advanced structure

In all previous examples we fudged a bit regarding the markup actually -allowed to be used before the toc_begin command opening the -document.

-[include FILE]
-[vset VAR VALUE]
-[toc_begin GROUPTITLE TITLE]
-...
-[toc_end]
-

Even more important, these two commands are allowed anywhere where a -markup command is allowed, without regard for any other -structure.

-[toc_begin GROUPTITLE TITLE]
-[include FILE]
-[vset VAR VALUE]
-...
-[toc_end]
-

The only restriction include has to obey is that the contents of -the included file must be valid at the place of the inclusion. I.e. a -file included before toc_begin may contain only the templating -commands vset and include, a file included in a division -may contain only items or divisions commands, etc.

Escapes

Beyond the 6 commands shown so far we have two more available. -However their function is not the marking up of toc structure, but the -insertion of characters, namely [ and ]. -These commands, lb and rb respectively, are required -because our use of [ and ] to bracket markup commands makes it -impossible to directly use [ and ] within the text.

Our example of their use are the sources of the last sentence in the -previous paragraph, with some highlighting added.

-  ...
-  These commands, [cmd lb] and [cmd lb] respectively, are required
-  because our use of [lb] and [rb] to bracket markup commands makes it
-  impossible to directly use [lb] and [rb] within the text.
-  ...
-

Bugs, Ideas, Feedback

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

Keywords

doctoc commands, doctoc language, doctoc markup, doctoc syntax, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctoc_lang_syntax.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_lang_syntax.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc_lang_syntax.html +++ /dev/null @@ -1,203 +0,0 @@ - -

- -

doctoc_lang_syntax(n) 1.0 tcllib "Documentation tools"

Name

doctoc_lang_syntax - doctoc language syntax

Table Of Contents
Description
Fundamentals
Lexical definitions
Syntax
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

This document contains the formal specification of the syntax of the -doctoc markup language, version 1.1 in Backus-Naur-Form. This document -is intended to be a reference, complementing the -doctoc language command reference. -A beginner should read the much more informally written -doctoc language introduction first before trying to -understand either this document or the command reference.

Fundamentals

In the broadest terms possible the doctoc markup language is -like SGML and similar languages. A document written in this language -consists primarily of markup commands, with text embedded into it at -some places.

Each markup command is a just Tcl command surrounded by a matching -pair of [ and ]. Which commands are available, -and their arguments, i.e. syntax is specified in the -doctoc language command reference.

In this document we specify first the lexeme, and then the syntax, -i.e. how we can mix text and markup commands with each other.

Lexical definitions

In the syntax rules listed in the next section

<TEXT> stands for all text except markup commands.
Any XXX stands for the markup command [xxx] including its -arguments. Each markup command is a Tcl command surrounded by a -matching pair of [ and ]. Inside of these -delimiters the usual rules for a Tcl command apply with regard to word -quotation, nested commands, continuation lines, etc.
<WHITE> stands for all text consisting only of spaces, newlines, -tabulators and the comment markup command.

Syntax

The rules listed here specify only the syntax of doctoc documents. The -lexical level of the language was covered in the previous section.

Regarding the syntax of the (E)BNF itself

The construct { X } stands for zero or more occurrences of X.
The construct [ X ] stands for zero or one occurrence of X.

The syntax:

-toc       = defs
-            TOC_BEGIN
-            contents
-            TOC_END
-            { <WHITE> }
-defs      = { INCLUDE | VSET | <WHITE> }
-contents  = { defs entry } [ defs ]
-entry     = ITEM | division
-division  = DIVISION_START
-            contents
-            DIVISION_END
-

Bugs, Ideas, Feedback

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

Keywords

doctoc commands, doctoc language, doctoc markup, doctoc syntax, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctoc_plugin_apiref.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_plugin_apiref.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc_plugin_apiref.html +++ /dev/null @@ -1,443 +0,0 @@ - -

- -

doctoc_plugin_apiref(n) 1.0 tcllib "Documentation tools"

Name

doctoc_plugin_apiref - doctoc plugin API reference

Table Of Contents
Synopsis
Description
OVERVIEW
FRONTEND COMMANDS
PLUGIN COMMANDS -
- Management commands
- Formatting commands
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

- -

Description

This document is intended for plugin writers, i.e. developers -wishing to write a toc formatting engine for some output -format X.

It specifies the interaction between the doctools::toc -package and its plugins, i.e. the interface any toc formatting engine -has to comply with.

This document deals with version 1 of the interface.

A reader who is on the other hand more interested in the markup -language itself should start with the -doctoc language introduction and proceed from there to the -formal specifications, i.e. the doctoc language syntax and -the doctoc language command reference.

OVERVIEW

The API for a toc formatting engine consists of two major sections.

FRONTEND COMMANDS

This section specifies the set of commands through which a plugin, -also known as a toc formatting engine, is able to query the -frontend. These commands are provided by the frontend and linked into -the plugin interpreter.

I.e. a toc formatting engine can assume that all of the following -commands are present when any of its own commands (as specified in -section PLUGIN COMMANDS) are executed.

dt_fmap symfname

Query command. It returns the actual pathname to use in the output in -place of the symbolic filename symfname. It will return the -unchanged input if no mapping was established for symfname.

The required mappings are established with the method map of -a frontend, as explained in section OBJECT METHODS -of the documentation for the package doctools::toc.

dt_format

Query command. It returns the name of the format associated with the -toc formatting engine.

dt_read file

dt_source file

Controlled filesystem access. This command allows the toc formatting -engine to load additional Tcl code it may need. -Only files which are either in the same directory as the file -containing the engine, or below it, can be loaded. Trying to load a -file outside of this directory causes an error.

ex_cappend text

Appends a string to the output in the current context. This command -should rarely be used by macros or application code.

ex_cget varname

Retrieves the value of variable varname, defined in the current -context.

ex_cis cname

Determines whether or not the name of the current context is -cname.

ex_cname

Returns the name of the current context.

ex_cpop cname

Pops a context from the context stack, returning all accumulated -output in that context. The context must be named cname, or an -error results.

ex_cpush cname

Pushes a context named cname onto the context stack. The -context must be popped by cpop before expansion ends or an -error results.

ex_cset varname value

Sets variable varname to value in the current context.

ex_lb ?newbracket?

ex_rb ?newbracket?

PLUGIN COMMANDS

Management commands

The management commands a plugin has to provide are used by the -frontend to

initialize and shutdown the plugin
determine the number of passes it has - to make over the input
initialize and shutdown each pass
query and initialize engine parameters

After the plugin has been loaded and the frontend commands are -established the commands will be called in the following sequence:

-    toc_numpasses -> n
-    toc_listvariables -> vars
-    toc_varset var1 value1
-    toc_varset var2 value2
-    ...
-    toc_varset varK valueK
-    toc_initialize
-    toc_setup 1
-    ...
-    toc_setup 2
-    ...
-    ...
-    toc_setup n
-    ...
-    toc_postprocess
-    toc_shutdown
-    ...
-

I.e. first the number of passes and the set of available engine -parameters is established, followed by calls setting the -parameters. That second part is optional.

In each of the passes, i.e. after the calls of toc_setup the -frontend will process the input and call the formatting commands as -markup is encountered. This means that the sequence of formatting -commands is determined by the grammar of the doctoc markup language, -as specified in the doctoc language syntax specification.

A different way of looking at the sequence is:

First some basic parameters are determined.
Then everything starting at the first toc_varset to -toc_shutdown forms a run, the formatting of a -single input. Each run can be followed by more.
Embedded within each run we have one or more passes, -each starting with toc_setup and going until either the next -toc_setup or toc_postprocess is reached.
-
If more than one pass is required to perform the formatting only the -output of the last pass is relevant. The output of all the previous, -preparatory passes is ignored.

The commands, their names, signatures, and responsibilities are, in -detail:

toc_initialize

toc_listvariables

Initialization/Shutdown and Engine parameters. -Second command is called after the plugin code has been loaded, -i.e. immediately after toc_numpasses. -It has to return a list containing the names of the parameters the -frontend can set to configure the engine. This list can be empty.

toc_numpasses

toc_postprocess text

Expected to return a value, the final result of formatting the input.

toc_setup n

toc_shutdown

toc_varset varname text

Engine parameters. -This command is called by the frontend to set an engine parameter to a -particular value. -The parameter to change is specified by varname, the value to -set in text.

The command has to throw an error if an unknown varname is -used. Only the names returned by toc_listvariables have to be -considered as known.

The values of all engine parameters have to persist between passes and -runs.

Formatting commands

The formatting commands have to implement the formatting for the -output format, for all the markup commands of the doctoc markup -language, except lb, rb, vset, include, and -comment. These exceptions are processed by the frontend and are -never seen by the plugin. In return a command for the formatting of -plain text has to be provided, something which has no markup in the -input at all.

This means, that each of the five markup commands specified in the -doctoc language command reference and outside of the set of -exceptions listed above has an equivalent formatting command which -takes the same arguments as the markup command and whose name is the -name of markup command with the prefix fmt_ added to it.

To avoid essentially duplicating the command reference we do not list -any of the command here and simply refer the reader to the -doctoc language command reference for their signature and -description. The sole exception is the plain text formatter, which has -no equivalent markup command.

The calling sequence of formatting commands is not as rigid as for the -management commands, but determined by the grammar of the doctoc -markup language, as specified in the doctoc language syntax -specification.

fmt_plain_text text

No associated markup command.

Called by the frontend for any plain text encountered in the -input. It has to perform any and all special processing required for -plain text.

The formatted text is expected as the result of the command, -and added to the output. If no special processing is required it has -to simply return its argument without change.

Bugs, Ideas, Feedback

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

Keywords

formatting engine, markup, plugin, semantic markup, table of contents, toc, toc formatter

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctools.html Index: embedded/www/tcllib/files/modules/doctools/doctools.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools.html +++ /dev/null @@ -1,501 +0,0 @@ - -

- -

doctools(n) 1.4.21 tcllib "Documentation tools"

Name

doctools - doctools - Processing documents

Table Of Contents
Synopsis
Description
PUBLIC API -
- PACKAGE COMMANDS
- OBJECT COMMAND
- OBJECT METHODS
- OBJECT CONFIGURATION
- FORMAT MAPPING
-
PREDEFINED ENGINES
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.2
package require doctools ?1.4.21?

::doctools::new objectName ?option value...?
::doctools::help
::doctools::search path
objectName method ?arg arg ...?
objectName configure
objectName configure option
objectName configure -option value...
objectName cget -option
objectName destroy
objectName format text
objectName map symbolic actual
objectName parameters
objectName search path
objectName setparam name value
objectName warnings

Description

This package provides a class for the creation of objects able to -process and convert text written in the doctools markup -language into any output format X for which a -formatting engine is available.

A reader interested in the markup language itself should start with -the doctools language introduction and proceed from there to -the formal specifications, i.e. the doctools language syntax -and the doctools language command reference.

If on the other hand the reader wishes to write her own formatting -engine for some format, i.e. is a plugin writer then reading -and understanding the doctools plugin API reference is an -absolute necessity, as that document specifies the interaction between -this package and its plugins, i.e. the formatting engines, in detail.

PUBLIC API

PACKAGE COMMANDS

::doctools::new objectName ?option value...?

This command creates a new doctools object with an associated Tcl -command whose name is objectName. This object command is -explained in full detail in the sections OBJECT COMMAND -and OBJECT METHODS. The object command will be created -under the current namespace if the objectName is not fully -qualified, and in the specified namespace otherwise.

The options and their values coming after the name of the object are -used to set the initial configuration of the object.

::doctools::help

::doctools::search path

An error will be thrown if the path either does not exist, is -not a directory, or is not readable.

OBJECT COMMAND

All commands created by ::doctools::new have the following -general form and may be used to invoke various operations on their -doctools converter object.

objectName method ?arg arg ...?: The method method and its arg'uments determine the exact -behavior of the command. See section OBJECT METHODS for -the detailed specifications.

OBJECT METHODS

objectName configure

The method returns a list of all known options and their current -values when called without any arguments.

objectName configure option

The method behaves like the method cget when called with a -single argument and returns the value of the option specified by said -argument.

objectName configure -option value...

The method reconfigures the specified options of the object, -setting them to the associated values, when called with an even -number of arguments, at least two.

The legal options are described in the section -OBJECT CONFIGURATION.

objectName cget -option

This method expects a legal configuration option as argument and will -return the current value of that option for the object the method was -invoked for.

The legal configuration options are described in section -OBJECT CONFIGURATION.

objectName destroy

This method destroys the object it is invoked for.

objectName format text

This method runs the text through the configured formatting -engine and returns the generated string as its result. An error will -be thrown if no -format was configured for the object.

The method assumes that the text is in doctools format as -specified in the companion document doctools_fmt. Errors will -be thrown otherwise.

objectName map symbolic actual

This methods add one entry to the per-object mapping from -symbolic filenames to the actual uris. -The object just stores this mapping and makes it available to the -configured formatting engine through the command dt_fmap. -This command is described in more detail in the -doctools plugin API reference which specifies the interaction -between the objects created by this package and doctools formatting -engines.

objectName parameters

objectName search path

This method extends the per-object list of paths searched for doctools -formatting engines. See also the command ::doctools::search on -how to extend the per-package list of paths. Note that the path -entered last will be searched first. -For more details see section FORMAT MAPPING.

objectName setparam name value

objectName warnings

This method returns a list containing all the warnings which were -generated by the configured formatting engine during the last -invocation of the method format.

OBJECT CONFIGURATION

All doctools objects understand the following configuration options:

-file file

The argument of this option is stored in the object and made available -to the configured formatting engine through the commands dt_file -and dt_mainfile. -These commands are described in more detail in the companion document -doctools_api which specifies the API between the object and -formatting engines.

The default value of this option is the empty string.

The configured formatting engine should interpret the value as the -name of the file containing the document which is currently processed.

-ibase file

The argument of this option is stored in the object and used as the -base path for resolution of relative include paths. If this option is -not set (empty string) the value of -file is used instead.

Note that -file and -ibase, while similar looking, -are actually very different. The value of -file is used by -some engines for the generation of proper relative references between -output documents (HTML). As such this is a destination -path. The -ibase on the other hand is used to resolve -relative include paths, and as such deals with source paths.

The default value of this option is the empty string.

-module text

The argument of this option is stored in the object and made available -to the configured formatting engine through the command dt_module. -This command is described in more detail in the companion document -doctools_api which specifies the API between the object and -formatting engines.

The default value of this option is the empty string.

The configured formatting engine should interpret the value as the -name of the module the file containing the document which is currently -processed belongs to.

-format text

The section FORMAT MAPPING explains in detail how the -package and object will look for engine implementations.

-deprecated boolean

This option is a boolean flag. The object will generate warnings if -this flag is set and the text given to method format contains -the deprecated markup command strong. -Its default value is FALSE. In other words, no warnings will -be generated.

-copyright text

The argument of this option is stored in the object and made available -to the configured formatting engine through the command dt_copyright. -This command is described in more detail in the companion document -doctools_api which specifies the API between the object and -formatting engines.

The default value of this option is the empty string.

The configured formatting engine should interpret the value as a -copyright assignment for the document which is currently processed, or -the package described by it.

This information must be used if and only if the engine is unable to -find any copyright assignments within the document itself. Such are -specified by the formatting command copyright. This command is -described in more detail in the companion document doctools_fmt -which specifies the doctools format itself.

FORMAT MAPPING

The package and object will perform the following algorithm when -trying to map a format name foo to a file containing an -implementation of a formatting engine for foo:

If foo is the name of an existing file then this file is -directly taken as the implementation.
If not, the list of per-object search paths is searched. For each -directory in the list the package checks if that directory contains a -file "fmt.foo". If yes, then that file is taken as the -implementation.
-
Note that this list of paths is initially empty and can be extended -through the object method search.
If not, the list of package paths is searched. -For each directory in the list the package checks if that directory -contains a file "fmt.foo". If yes, then that file is taken -as the implementation.
-
This list of paths can be extended -through the command ::doctools::search. -It contains initially one path, the subdirectory "mpformats" of -the directory the package itself is located in. -In other words, if the package implementation "doctools.tcl" is -installed in the directory "/usr/local/lib/tcllib/doctools" then -it will by default search the -directory "/usr/local/lib/tcllib/doctools/mpformats" for format -implementations.
The mapping fails.

PREDEFINED ENGINES

The package provides predefined engines for the following -formats. Some of the engines support parameters. These will be -explained below as well.

html

This engine generates HTML markup, for processing by web browsers and -the like. This engine supports four parameters:

footer

This can be used to insert boilerplate footer markup into the -generated document.

header

The value for this parameter has to be valid selfcontained HTML markup -for the body section of a HTML document. The default value is the -empty string. The value is inserted into the generated output just -after the <body> tag, starting the body of the generated HTML.

This can be used to insert boilerplate header markup into the -generated document.

meta

This can be used to insert boilerplate meta data markup into the -generated document, like references to a stylesheet, standard meta -keywords, etc.

xref

The value for this parameter has to be a list of triples specifying -cross-reference information. This information is used by the engine to -create more hyperlinks. Each triple is a list containing a pattern, -symbolic filename and fragment reference, in this order. If a pattern -is specified multiple times the last occurrence of the pattern will be -used.

The engine will consult the xref database when encountering specific -commands and will create a link if the relevant text matches one of -the patterns. No link will be created if no match was found. The link -will go to the uri file#fragment listed in the relevant -triple, after conversion of the symbolic file name to the actual uri -via dt_fmap (see the doctools plugin API reference). -This file-to-uri mapping was build by calls to the method map -of the doctools object (See section OBJECT METHODS).

The following formatting commands will consult the xref database:

cmd word: The command will look for the patterns sa,word, and -word, in this order. If this fails if it will convert word -to all lowercase and try again.
syscmd word: The command will look for the patterns sa,word, and -word, in this order. If this fails if it will convert word -to all lowercase and try again.
term word: The command will look for the patterns kw,word, -sa,word, and word, in this order. If this fails if -it will convert word to all lowercase and try again.
package word: The command will look for the patterns sa,word, -kw,word, and word, in this order. If this fails if -it will convert word to all lowercase and try again.
see_also word...: The command will look for the patterns sa,word, and -word, in this order, for each word given to the -command. If this fails if it will convert word to all lowercase -and try again.
keywords word...: The command will look for the patterns kw,word, and -word, in this order, for each word given to the -command. If this fails if it will convert word to all lowercase -and try again.

latex

This engine generates output suitable for the latex text -processor coming out of the TeX world.

list

This engine retrieves version, section and title of the manpage from -the document. As such it can be used to generate a directory listing -for a set of manpages.

nroff

This engine generates nroff output, for processing by nroff, -or groff. The result will be standard man pages as they are -known in the unix world.

null

This engine generates no outout at all. This can be used if one just -wants to validate some input.

tmml

This engine generates TMML markup as specified by Joe English. The Tcl -Manpage Markup Language is a derivate of XML.

wiki

This engine generates Wiki markup as understood by Jean Claude -Wippler's wikit application.

Bugs, Ideas, Feedback

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

Keywords

HTML, TMML, conversion, documentation, manpage, markup, nroff

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctools_intro.html Index: embedded/www/tcllib/files/modules/doctools/doctools_intro.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools_intro.html +++ /dev/null @@ -1,194 +0,0 @@ - -

- -

doctools_intro(n) 1.0 tcllib "Documentation tools"

Name

doctools_intro - doctools introduction

Table Of Contents
Description
RELATED FORMATS
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

doctools (short for documentation tools) stands for -a set of related, yet different, entities which are working together -for the easy creation and transformation of documentation. These are

A tcl based language for the semantic markup of text. Markup is -represented by Tcl commands interspersed with the actual text.
A package providing the ability to read and transform texts written in -that markup language. It is important to note that the actual -transformation of the input text is delegated to plugins.
An API describing the interface between the package above and a -plugin.

Which of the more detailed documents are relevant to the reader of -this introduction depends on their role in the documentation process.

A writer of documentation has to understand the markup language -itself. A beginner to doctools should read the more informally written -doctools language introduction first. Having digested this -the formal doctools language syntax specification should -become understandable. A writer experienced with doctools may only -need the doctools language command reference from time to -time to refresh her memory.
-
While a document is written the dtplite application can be -used to validate it, and after completion it also performs the -conversion into the chosen system of visual markup, be it *roff, HTML, -plain text, wiki, etc.
A processor of documentation written in the doctools -markup language has to know which tools are available for use.
-
The main tool is the aforementioned dtplite application -provided by Tcllib. A more powerful one (in terms of options and -ability to configure it) is the dtp application, provided by -Tclapps. -At the bottom level, common to both applications, however sits the -package doctools, providing the basic facilities to read and -process files containing text in the doctools format.
At last, but not least, plugin writers have to understand the -interaction between the doctools package and its plugins, as -described in the doctools plugin API reference.

RELATED FORMATS

doctools does not stand alone, it has two companion formats. These are -called docidx and doctoc, and they are for the markup of -keyword indices, and tables of contents, -respectively. -They are described in their own sets of documents, starting at the -docidx introduction and the doctoc introduction, -respectively.

Bugs, Ideas, Feedback

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

Keywords

markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctools_lang_cmdref.html Index: embedded/www/tcllib/files/modules/doctools/doctools_lang_cmdref.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools_lang_cmdref.html +++ /dev/null @@ -1,534 +0,0 @@ - -

- -

doctools_lang_cmdref(n) 1.0 tcllib "Documentation tools"

Name

doctools_lang_cmdref - doctools language command reference

Table Of Contents
Synopsis
Description
Commands
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

arg text
arg_def type name ?mode?
bullet
call args
category text
class text
cmd text
cmd_def command
comment plaintext
const text
copyright text
def text
description
enum
emph text
example text
example_begin
example_end
file text
fun text
image name ?label?
include filename
item
keywords args
lb
list_begin what
list_end
lst_item text
manpage_begin command section version
manpage_end
method text
moddesc text
namespace text
nl
opt text
opt_def name ?arg?
option text
package text
para
rb
require package ?version?
section name
sectref id ?text?
sectref-external text
see_also args
strong text
subsection name
syscmd text
term text
titledesc desc
tkoption_def name dbname dbclass
type text
uri text ?text?
usage args
var text
vset varname value
vset varname
widget text

Description

This document specifies both names and syntax of all the commands -which together are the doctools markup language, version 1. -As this document is intended to be a reference the commands are listed -in alphabetical order, and the descriptions are relatively short. -A beginner should read the much more informally written -doctools language introduction first.

Commands

arg text

Text markup. The argument text is marked up as the argument of -a command. Main uses are the highlighting of command arguments in -free-form text, and for the argument parameters of the markup commands -call and usage.

arg_def type name ?mode?

Text structure. List element. Argument list. Automatically closes the -previous list element. Specifies the data-type of the described -argument of a command, its name and its i/o-mode. The -latter is optional.

bullet

Deprecated. Text structure. List element. Itemized list. See -item for the canonical command to open a list item in an -itemized list.

call args

Text structure. List element. Definition list. Automatically closes -the previous list element. Defines the term as a command and its -arguments. -The first argument is the name of the command described by the -following free-form text, and all arguments coming after that are -descriptions of the command's arguments. -It is expected that the arguments are marked up with arg, -method, option etc., as is appropriate, and that the -command itself is marked up with cmd. -It is expected that the formatted term is not only printed in place, -but also in the table of contents of the document, or synopsis, -depending on the output format.

category text

Document information. Anywhere. This command registers its plain text -arguments as the category this document belongs to. If this command is -used multiple times the last value specified is used.

class text

Text markup. The argument is marked up as the name of a -class. The text may have other markup already applied to -it. Main use is the highlighting of class names in free-form text.

cmd text

Text markup. The argument text is marked up as the name of a -Tcl command. The text may have other markup already applied -to it. Main uses are the highlighting of commands in free-form text, -and for the command parameters of the markup commands call and -usage.

cmd_def command

Text structure. List element. Command list. Automatically closes the -previous list element. The argument specifies the name of the -Tcl command to be described by the list element. Expected to -be marked up in the output as if it had been formatted with cmd.

comment plaintext

Text markup. The argument text is marked up as a comment standing -outside of the actual text of the document. Main use is in free-form -text.

const text

Text markup. The argument is marked up as a constant value. The -text may have other markup already applied to it. Main use is the -highlighting of constants in free-form text.

copyright text

Document information. Anywhere. The command registers the plain text -argument as a copyright assignment for the manpage. When invoked more -than once the assignments are accumulated.

def text

Text structure. List element. Definition list. Automatically closes -the previous list element. The argument text is the term defined by -the new list element. Text markup can be applied to it.

description

Document structure. This command separates the header from the -document body. Implicitly starts a section named "DESCRIPTION" (See -command section).

enum

Text structure. List element. Enumerated list. Automatically closes -the previous list element.

emph text

Text markup. The argument text is marked up as emphasized. Main use is -for general highlighting of pieces of free-form text without attaching -special meaning to the pieces.

example text

Text structure, Text markup. This command marks its argument up as an -example. Main use is the simple embedding of examples in -free-form text. It should be used if the example does not need -special markup of its own. Otherwise use a sequence of -example_begin ... example_end.

example_begin

Text structure. This commands starts an example. All text until the -next example_end belongs to the example. Line breaks, spaces, -and tabs have to be preserved literally. Examples cannot be nested.

example_end

Text structure. This command closes the example started by the last -example_begin.

file text

Text markup. The argument is marked up as a file or -directory, i.e. in general a path. The text may have -other markup already applied to it. Main use is the highlighting of -paths in free-form text.

fun text

Text markup. The argument is marked up as the name of a -function. The text may have other markup already applied to -it. Main use is the highlighting of function names in free-form text.

image name ?label?

Text markup. The argument is the symbolic name of an image -and replaced with the image itself, if a suitable variant is found -by the backend. The second argument, should it be present, will be -interpreted the human-readable description of the image, and put -into the output in a suitable position, if such is supported by the -format. The HTML format, for example, can place it into the alt -attribute of image references.

include filename

Templating. The contents of the named file are interpreted as text -written in the doctools markup and processed in the place of the -include command. The markup in the file has to be self-contained. It -is not possible for a markup command to cross the file boundaries.

item

Text structure. List element. Itemized list. Automatically closes the -previous list element.

keywords args

Document information. Anywhere. This command registers all its plain text -arguments as keywords applying to this document. Each argument is a single -keyword. If this command is used multiple times all the arguments accumulate.

lb

Text. The command is replaced with a left bracket. Use in free-form text. -Required to avoid interpretation of a left bracket as the start of a markup -command.

list_begin what

Text structure. This command starts a list. The exact nature of the -list is determined by the argument what of the command. This -further determines which commands are have to be used to start the -list elements. Lists can be nested, i.e. it is allowed to start a new -list within a list element.

The allowed types (and their associated item commands) are:

arguments: arg_def.
commands: cmd_def.
definitions: def and call.
enumerated: enum
itemized: item
options: opt_def
tkoptions: tkoption_def

Additionally the following names are recognized as shortcuts for some -of the regular types:

args: Short for arguments.
cmds: Short for commands.
enum: Short for enumerated.
item: Short for itemized.
opts: Short for options.

At last the following names are still recognized for backward -compatibility, but are otherwise considered to be deprecated.

arg: Deprecated. See arguments.
bullet: Deprecated. See itemized.
cmd: Deprecated. See commands.
opt: Deprecated. See options.
tkoption: Deprecated. See tkoptions.

list_end

Text structure. This command closes the list opened by the last -list_begin command coming before it.

lst_item text

Deprecated. Text structure. List element. Definition list. See -def for the canonical command to open a general list item in a -definition list.

manpage_begin command section version

Document structure. The command to start a manpage. The arguments are -the name of the command described by the manpage, the -section of the manpages this manpage resides in, and the -version of the module containing the command. All arguments have -to be plain text, without markup.

manpage_end

Document structure. Command to end a manpage/document. Anything in the document -coming after this command is in error.

method text

Text markup. The argument text is marked up as the name of an -object method, i.e. subcommand of a Tcl command. The -text may have other markup already applied to it. Main uses are the -highlighting of method names in free-form text, and for the command -parameters of the markup commands call and usage.

moddesc text

Document information. Header. Registers the plain text argument as a short -description of the module the manpage resides in.

namespace text

Text markup. The argument text is marked up as a namespace name. The -text may have other markup already applied to it. Main use is the -highlighting of namespace names in free-form text.

nl

Deprecated. Text structure. See para for the canonical -command to insert paragraph breaks into the text.

opt text

Text markup. The argument text is marked up as optional. The text may -have other markup already applied to it. Main use is the highlighting of -optional arguments, see the command arg arg.

opt_def name ?arg?

Text structure. List element. Option list. Automatically closes the -previous list element. Specifies name and arguments of the -option described by the list element. It is expected that the -name is marked up using option.

option text

Text markup. The argument is marked up as option. The text may -have other markup already applied to it. Main use is the highlighting -of options, also known as command-switches, in either free-form text, -or the arguments of the call and usage commands.

package text

Text markup. The argument is marked up as the name of a -package. The text may have other markup already applied to -it. Main use is the highlighting of package names in free-form text.

para

Text structure. This command breaks free-form text into -paragraphs. Each command closes the paragraph coming before it and -starts a new paragraph for the text coming after it. Higher-level -forms of structure are sections and subsections.

rb

Text. The command is replaced with a right bracket. Use in free-form text. -Required to avoid interpretation of a right bracket as the end of a markup -command.

require package ?version?

Document information. Header. This command registers its argument -package as the name of a package or application required by the -described package or application. A minimum version can be provided as -well. This argument can be marked up. The usual markup is opt.

section name

Text structure. This command starts a new named document section. The -argument has to be plain text. Implicitly closes the last paragraph -coming before it and also implicitly opens the first paragraph of the -new section.

sectref id ?text?

Text markup. Formats a reference to the section identified by id. -If no text is specified the title of the referenced section is -used in the output, otherwise text is used.

sectref-external text

Text markup. Like sectref, except that the section is assumed to -be in a different document and therefore doesn't need to be identified, -nor are any checks for existence made. Only the text to format is needed.

see_also args

Document information. Anywhere. The command defines direct cross-references -to other documents. Each argument is a plain text label identifying the -referenced document. If this command is used multiple times all the arguments -accumulate.

strong text

Deprecated. Text markup. See emph for the canonical -command to emphasize text.

subsection name

Text structure. This command starts a new named subsection of a -section. The argument has to be plain text. Implicitly closes the last -paragraph coming before it and also implicitly opens the first -paragraph of the new subsection.

syscmd text

Text markup. The argument text is marked up as the name of an external -command. The text may have other markup already applied to it. Main -use is the highlighting of external commands in free-form text.

term text

Text markup. The argument is marked up as unspecific terminology. The -text may have other markup already applied to it. Main use is the -highlighting of important terms and concepts in free-form text.

titledesc desc

Document information. Header. Optional. Registers the plain text -argument as the title of the manpage. Defaults to the value registered -by moddesc.

tkoption_def name dbname dbclass

Text structure. List element. Widget option list. Automatically closes -the previous list element. Specifies the name of the option as -used in scripts, the name used by the option database (dbname), -and its class (dbclass), i.e. its type. It is expected that the -name is marked up using option.

type text

Text markup. The argument is marked up as the name of a -data type. The text may have other markup already applied to -it. Main use is the highlighting of data types in free-form text.

uri text ?text?

Text markup. The argument is marked up as an uri (i.e. a -uniform resource identifier. The text may have other markup -already applied to it. Main use is the highlighting of uris in -free-form text. The second argument, should it be present, will be -interpreted the human-readable description of the uri. In other words, -as its label. Without an explicit label the uri will be its own label.

usage args

Text markup. See call for the full description, this command is -syntactically identical, as it is in its expectations for the markup -of its arguments. -In contrast to call it is however not allowed to generate output -where this command occurs in the text. The command is silent. -The formatted text may only appear in a different section of the -output, for example a table of contents, or synopsis, depending on the -output format.

var text

Text markup. The argument is marked up as the name of a -variable. The text may have other markup already applied to -it. Main use is the highlighting of variables in free-form text.

vset varname value

Templating. In this form the command sets the named document variable -to the specified value. It does not generate output. I.e. the -command is replaced by the empty string.

vset varname

Templating. In this form the command is replaced by the value of the -named document variable

widget text

Text markup. The argument is marked up as the name of a -widget. The text may have other markup already applied to -it. Main use is the highlighting of widget names in free-form text.

Bugs, Ideas, Feedback

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

Keywords

doctools commands, doctools language, doctools markup, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctools_lang_faq.html Index: embedded/www/tcllib/files/modules/doctools/doctools_lang_faq.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools_lang_faq.html +++ /dev/null @@ -1,184 +0,0 @@ - -

- -

doctools_lang_faq(n) 1.0 tcllib "Documentation tools"

Name

doctools_lang_faq - doctools language faq

Table Of Contents
Description
OVERVIEW -
- What is this document?
-
EXAMPLES -
- Where do I find doctools examples?
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

OVERVIEW

What is this document?

This document is currently mainly a placeholder, to be filled with -commonly asked questions about the doctools markup language -and companions, and their answers.

Please report any questions (and, if possible, answers) we should -consider for this document as explained in the section -Bugs, Ideas, Feedback below.

EXAMPLES

Where do I find doctools examples?

We have no direct examples of documents written using doctools -markup. However the doctools processor dtplite does generate -a table of contents when processing a set of documents written in -doctools markup. The intermediate file for it uses doctools -markup and is not deleted when generation completes. Such files can -therefore serve as examples.

dtplite is distributed as part of Tcllib, so to get it you -need one of

A snapshot of Tcllib. How to retrieve such a snapshot and the -tools required for this are described at -Development Snapshots
A Tcllib release archive. They are available at the home -page.

Bugs, Ideas, Feedback

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

Keywords

doctools commands, doctools language, doctools markup, doctools syntax, examples, faq, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctools_lang_intro.html Index: embedded/www/tcllib/files/modules/doctools/doctools_lang_intro.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools_lang_intro.html +++ /dev/null @@ -1,633 +0,0 @@ - -

- -

doctools_lang_intro(n) 1.0 tcllib "Documentation tools"

Name

doctools_lang_intro - doctools language introduction

Table Of Contents
Description -
- Fundamentals
- Basic structure
- Advanced structure
- Text structure
- Text markup
- Escapes
- Cross-references
- Examples
- Lists
-
FURTHER READING
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

This document is an informal introduction to version 1 of the doctools -markup language based on a multitude of examples. After reading this a -writer should be ready to understand the two parts of the formal -specification, i.e. the doctools language syntax specification -and the doctools language command reference.

Fundamentals

In the broadest terms possible the doctools markup language -is LaTeX-like, instead of like SGML and similar languages. A document -written in this language consists primarily of text, with markup -commands embedded into it.

-  ... [list_begin enumerated] ...
-

-  ... [call [cmd foo] \\
-          [arg bar]] ...
-

-  ... [term {complex concept}] ...
-

-  ... [opt "[arg key] [arg value]"] ...
-

Basic structure

The most simple document which can be written in doctools is

-    [manpage_begin NAME SECTION VERSION]
-[see_also doctools_intro]
-[see_also doctools_lang_cmdref]
-[see_also doctools_lang_faq]
-[see_also doctools_lang_syntax]
-[keywords {doctools commands}]
-[keywords {doctools language}]
-[keywords {doctools markup}]
-[keywords {doctools syntax}]
-[keywords markup]
-[keywords {semantic markup}]
-    [description]
-    [vset CATEGORY doctools]
-[include ../doctools2base/include/feedback.inc]
-[manpage_end]
-

This also shows us that all doctools documents are split into two -parts, the header and the body. Everything coming before -[description] belongs to the header, and everything coming -after belongs to the body, with the whole document bracketed by the -two manpage_* commands. Before and after these opening and -closing commands we have only whitespace.

In the remainder of this section we will discuss only the contents of -the header, the structure of the body will be discussed in the section -Text structure.

The header section can be empty, and otherwise may contain only an -arbitrary sequence of the four so-called header commands, plus -whitespace. These commands are

titledesc
moddesc
require
copyright

They provide, through their arguments, additional information about -the document, like its title, the title of the larger group the -document belongs to (if applicable), the requirements of the -documented packages (if applicable), and copyright assignments. All of -them can occur multiple times, including none, and they can be used in -any order. -However for titledesc and moddesc only the last occurrence -is taken. For the other two the specified information is accumulated, -in the given order. Regular text is not allowed within the header.

Given the above a less minimal example of a document is

-[manpage_begin NAME SECTION VERSION]
-[copyright {YEAR AUTHOR}]
-[titledesc TITLE]
-[moddesc   MODULE_TITLE]
-[require   PACKAGE VERSION]
-[require   PACKAGE]
-[description]
-[manpage_end]
-

Remember that the whitespace is optional. The document

-    [manpage_begin NAME SECTION VERSION]
-    [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
-    [require PACKAGE VERSION][require PACKAGE][description]
-    [vset CATEGORY doctools]
-[include ../doctools2base/include/feedback.inc]
-[manpage_end]
-

has the same meaning as the example before.

On the other hand, if whitespace is present it consists not -only of any sequence of characters containing the space character, -horizontal and vertical tabs, carriage return, and newline, but it may -contain comment markup as well, in the form of the comment -command.

-[comment { ... }]
-[manpage_begin NAME SECTION VERSION]
-[copyright {YEAR AUTHOR}]
-[titledesc TITLE]
-[moddesc   MODULE_TITLE][comment { ... }]
-[require   PACKAGE VERSION]
-[require   PACKAGE]
-[description]
-[manpage_end]
-[comment { ... }]
-

Advanced structure

In the simple examples of the last section we fudged a bit regarding -the markup actually allowed to be used before the manpage_begin -command opening the document.

-[include FILE]
-[vset VAR VALUE]
-[manpage_begin NAME SECTION VERSION]
-[description]
-[manpage_end]
-

Even more important, these two commands are allowed anywhere where a -markup command is allowed, without regard for any other -structure. I.e. for example in the header as well.

-[manpage_begin NAME SECTION VERSION]
-[include FILE]
-[vset VAR VALUE]
-[description]
-[manpage_end]
-

The only restriction include has to obey is that the contents of -the included file must be valid at the place of the inclusion. I.e. a -file included before manpage_begin may contain only the -templating commands vset and include, a file included in -the header may contain only header commands, etc.

Text structure

The body of the document consists mainly of text, possibly split into -sections, subsections, and paragraphs, with parts marked up to -highlight various semantic categories of text, and additional -structure through the use of examples and (nested) lists.

This section explains the high-level structural commands, with -everything else deferred to the following sections.

The simplest way of structuring the body is through the introduction -of paragraphs. The command for doing so is para. Each occurrence -of this command closes the previous paragraph and automatically opens -the next. The first paragraph is automatically opened at the beginning -of the body, by description. In the same manner the last -paragraph automatically ends at manpage_end.

-[manpage_begin NAME SECTION VERSION]
-[description]
- ...
-[para]
- ...
-[para]
- ...
-[manpage_end]
-

Empty paragraphs are ignored.

A structure coarser than paragraphs are sections, which allow the -writer to split a document into larger, and labeled, pieces. The -command for doing so is section. Each occurrence of this command -closes the previous section and automatically opens the next, -including its first paragraph. The first section is automatically -opened at the beginning of the body, by description (This -section is labeled "DESCRIPTION"). In the same manner the last section -automatically ends at manpage_end.

Empty sections are not ignored. We are free to (not) use -paragraphs within sections.

-[manpage_begin NAME SECTION VERSION]
-[description]
- ...
-[section {Section A}]
- ...
-[para]
- ...
-[section {Section B}]
- ...
-[manpage_end]
-

Between sections and paragraphs we have subsections, to split sections. -The command for doing so is subsection. Each occurrence of this -command closes the previous subsection and automatically opens the -next, including its first paragraph. A subsection is automatically -opened at the beginning of the body, by description, and at the -beginning of each section. In the same manner the last subsection -automatically ends at manpage_end.

Empty subsections are not ignored. We are free to (not) use -paragraphs within subsections.

-[manpage_begin NAME SECTION VERSION]
-[description]
- ...
-[section {Section A}]
- ...
-[subsection {Sub 1}]
- ...
-[para]
- ...
-[subsection {Sub 2}]
- ...
-[section {Section B}]
- ...
-[manpage_end]
-

Text markup

Having handled the overall structure a writer can impose on the -document we now take a closer at the text in a paragraph.

While most often this is just the unadorned content of the document we -do have situations where we wish to highlight parts of it as some type -of thing or other, like command arguments, command names, concepts, -uris, etc.

For this we have a series of markup commands which take the text to -highlight as their single argument. It should be noted that while -their predominant use is the highlighting of parts of a paragraph they -can also be used to mark up the arguments of list item commands, and -of other markup commands.

The commands available to us are

arg: Its argument is a the name of a command argument.
class: Its argument is a class name.
cmd: Its argument is a command name (Tcl command).
const: Its argument is a constant.
emph: General, non-semantic emphasis.
file: Its argument is a filename / path.
fun: Its argument is a function name.
method: Its argument is a method name
namespace: Its argument is namespace name.
opt: Its argument is some optional syntax element.
option: Its argument is a command line switch / widget option.
package: Its argument is a package name.
sectref: Its argument is the title of a section or subsection, - i.e. a section reference.
syscmd: Its argument is a command name (external, system command).
term: Its argument is a concept, or general terminology.
type: Its argument is a type name.
uri: Its argument is a uniform resource identifier, i.e an - external reference. A second argument can be used - to specify an explicit label for the reference in - question.
usage: The arguments describe the syntax of a Tcl command.
var: Its argument is a variable.
widget: Its argument is a widget name.

The example demonstrating the use of text markup is an excerpt from -the doctools language command reference, with some -highlighting added. -It shows their use within a block of text, as the arguments of a list -item command (call), and our ability to nest them.

-  ...
-  [call [cmd arg_def] [arg type] [arg name] [opt [arg mode]]]
-  Text structure. List element. Argument list. Automatically closes the
-  previous list element. Specifies the data-[arg type] of the described
-  argument of a command, its [arg name] and its i/o-[arg mode]. The
-  latter is optional.
-  ...
-

Escapes

Beyond the 20 commands for simple markup shown in the previous section -we have two more available which are technically simple markup. -However their function is not the marking up of phrases as specific -types of things, but the insertion of characters, namely [ -and ]. -These commands, lb and rb respectively, are required -because our use of [ and ] to bracket markup commands makes it -impossible to directly use [ and ] within the text.

Our example of their use are the sources of the last sentence in the -previous paragraph, with some highlighting added.

-  ...
-  These commands, [cmd lb] and [cmd lb] respectively, are required
-  because our use of [lb] and [rb] to bracket markup commands makes it
-  impossible to directly use [lb] and [rb] within the text.
-  ...
-

Cross-references

The last two commands we have to discuss are for the declaration of -cross-references between documents, explicit and implicit. They are -keywords and see_also. Both take an arbitrary number of -arguments, all of which have to be plain unmarked text. I.e. it is not -allowed to use markup on them. Both commands can be used multiple -times in a document. If that is done all arguments of all occurrences -of one of them are put together into a single set.

keywords: The arguments of this command are interpreted as keywords describing -the document. A processor can use this information to create an index -indirectly linking the containing document to all documents with the -same keywords.
see_also: The arguments of this command are interpreted as references to other -documents. A processor can format them as direct links to these -documents.

All the cross-reference commands can occur anywhere in the document -between manpage_begin and manpage_end. As such the writer -can choose whether she wants to have them at the beginning of the -body, or at its end, maybe near the place a keyword is actually -defined by the main content, or considers them as meta data which -should be in the header, etc.

Our example shows the sources for the cross-references of this -document, with some highlighting added. Incidentally they are found -at the end of the body.

-  ...
-  [see_also doctools_intro]
-  [see_also doctools_lang_syntax]
-  [see_also doctools_lang_cmdref]
-  [keywords markup {semantic markup}]
-  [keywords {doctools markup} {doctools language}]
-  [keywords {doctools syntax} {doctools commands}]
-  [manpage_end]
-

Examples

Where ever we can write plain text we can write examples too. For -simple examples we have the command example which takes a single -argument, the text of the argument. The example text must not contain -markup. If we wish to have markup within an example we have to use the -2-command combination example_begin / example_end instead.

The first opens an example block, the other closes it, and in between -we can write plain text and use all the regular text markup commands. -Note that text structure commands are not allowed. This also means -that it is not possible to embed examples and lists within an example. -On the other hand, we can use templating commands within -example blocks to read their contents from a file (Remember section -Advanced structure).

The source for the very first example in this document (see section -Fundamentals), with some highlighting added, is

-  [example {
-    ... [list_begin enumerated] ...
-  }]
-

Using example_begin / example_end this would look like

-  [example_begin]
-    ... [list_begin enumerated] ...
-  [example_end]
-

Lists

Where ever we can write plain text we can write lists too. The main -commands are list_begin to start a list, and list_end to -close one. The opening command takes an argument specifying the type -of list started it, and this in turn determines which of the eight -existing list item commands are allowed within the list to start list -items.

After the opening command only whitespace is allowed, until the first -list item command opens the first item of the list. Each item is a -regular series of paragraphs and is closed by either the next list -item command, or the end of the list. If closed by a list item command -this command automatically opens the next list item. A consequence of -a list item being a series of paragraphs is that all regular text -markup can be used within a list item, including examples and other -lists.

The list types recognized by list_begin and their associated -list item commands are:

arguments: (arg_def) This opens an argument (declaration) list. It -is a specialized form of a term definition list where the term is an -argument name, with its type and i/o-mode.
commands: (cmd_def) This opens a command (declaration) list. It -is a specialized form of a term definition list where the term is a -command name.
definitions: (def and call) This opens a general -term definition list. The terms defined by the list items are -specified through the argument(s) of the list item commands, either -general terms, possibly with markup (def), or Tcl commands with -their syntax (call).
enumerated: (enum) This opens a general enumerated list.
itemized: (item) -This opens a general itemized list.
options: (opt_def) This opens an option (declaration) list. It -is a specialized form of a term definition list where the term is an -option name, possibly with the option's arguments.
tkoptions: (tkoption_def) This opens a -widget option (declaration) list. It is a specialized form of -a term definition list where the term is the name of a configuration -option for a widget, with its name and class in the option database.

Our example is the source of the definition list in the previous -paragraph, with most of the content in the middle removed.

-  ...
-  [list_begin definitions]
-  [def [const arg]]
-  ([cmd arg_def]) This opens an argument (declaration) list. It is a
-  specialized form of a definition list where the term is an argument
-  name, with its type and i/o-mode.
-  [def [const itemized]]
-  ([cmd item])
-  This opens a general itemized list.
-  ...
-  [def [const tkoption]]
-  ([cmd tkoption_def]) This opens a widget option (declaration) list. It
-  is a specialized form of a definition list where the term is the name
-  of a configuration option for a widget, with its name and class in the
-  option database.
-  [list_end]
-  ...
-

Note that a list cannot begin in one (sub)section and end in -another. Differently said, (sub)section breaks are not allowed within -lists and list items. An example of this illegal construct is

-  ...
-  [list_begin itemized]
-  [item]
-  ...
-  [section {ILLEGAL WITHIN THE LIST}]
-  ...
-  [list_end]
-  ...
-

Bugs, Ideas, Feedback

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

Keywords

doctools commands, doctools language, doctools markup, doctools syntax, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctools_lang_syntax.html Index: embedded/www/tcllib/files/modules/doctools/doctools_lang_syntax.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools_lang_syntax.html +++ /dev/null @@ -1,231 +0,0 @@ - -

- -

doctools_lang_syntax(n) 1.0 tcllib "Documentation tools"

Name

doctools_lang_syntax - doctools language syntax

Table Of Contents
Description
Fundamentals
Lexical definitions
Syntax
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

This document contains the formal specification of the syntax of the -doctools markup language, version 1 in Backus-Naur-Form. This document -is intended to be a reference, complementing the -doctools language command reference. -A beginner should read the much more informally written -doctools language introduction first before trying to -understand either this document or the command reference.

Fundamentals

Each markup command is a just Tcl command surrounded by a matching -pair of [ and ]. Which commands are available, -and their arguments, i.e. syntax is specified in the -doctools language command reference.

In this document we specify first the lexeme, and then the syntax, -i.e. how we can mix text and markup commands with each other.

Lexical definitions

In the syntax rules listed in the next section

<TEXT> stands for all text except markup commands.
Any XXX stands for the markup command [xxx] including its -arguments. Each markup command is a Tcl command surrounded by a -matching pair of [ and ]. Inside of these -delimiters the usual rules for a Tcl command apply with regard to word -quotation, nested commands, continuation lines, etc.
<WHITE> stands for all text consisting only of spaces, newlines, -tabulators and the comment markup command.

Syntax

The rules listed here specify only the syntax of doctools -documents. The lexical level of the language was covered in the -previous section.

Regarding the syntax of the (E)BNF itself

The construct { X } stands for zero or more occurrences of X.
The construct [ X ] stands for zero or one occurrence of X.
The construct LIST_BEGIN<X> stands for the markup command -list_begin with X as its type argument.

The syntax:

-manpage = defs
-          MANPAGE_BEGIN
-          header
-          DESCRIPTION
-          body
-          MANPAGE_END
-          { <WHITE> }
-defs    = { INCLUDE | VSET | <WHITE> }
-header  = { TITLEDESC | MODDESC | COPYRIGHT | REQUIRE | defs | xref }
-xref    = KEYWORDS | SEE_ALSO | CATEGORY
-body    = paras { SECTION    sbody  }
-sbody   = paras { SUBSECTION ssbody }
-ssbody  = paras
-paras   = tblock { (PARA | NL) tblock }
-tblock  = { <TEXT> | defs | markup | xref | an_example | a_list }
-markup  = ARG     | CLASS | CMD     | CONST     | EMPH   | FILE
-        | FUN     | LB    | METHOD  | NAMESPACE | OPT    | OPTION
-        | PACKAGE | RB    | SECTREF | STRONG    | SYSCMD | TERM
-        | TYPE    | URI   | USAGE   | VAR       | WIDGET
-example = EXAMPLE
-        | EXAMPLE_BEGIN extext EXAMPLE_END
-extext  = { <TEXT> | defs | markup }
-a_list  = LIST_BEGIN<arguments>   argd_list   LIST_END
-        | LIST_BEGIN<commands>    cmdd_list   LIST_END
-        | LIST_BEGIN<definitions> def_list    LIST_END
-        | LIST_BEGIN<enumerated>  enum_list   LIST_END
-        | LIST_BEGIN<itemized>    item_list   LIST_END
-        | LIST_BEGIN<options>     optd_list   LIST_END
-        | LIST_BEGIN<tkoptions>   tkoptd_list LIST_END
-argd_list   = [ <WHITE> ] { ARG_DEF      paras }
-cmdd_list   = [ <WHITE> ] { CMD_DEF      paras }
-def_list    = [ <WHITE> ] { (DEF|CALL)   paras }
-enum_list   = [ <WHITE> ] { ENUM         paras }
-item_list   = [ <WHITE> ] { ITEM         paras }
-optd_list   = [ <WHITE> ] { OPT_DEF      paras }
-tkoptd_list = [ <WHITE> ] { TKOPTION_DEF paras }
-

Bugs, Ideas, Feedback

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

Keywords

doctools commands, doctools language, doctools markup, doctools syntax, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/doctools_plugin_apiref.html Index: embedded/www/tcllib/files/modules/doctools/doctools_plugin_apiref.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools_plugin_apiref.html +++ /dev/null @@ -1,491 +0,0 @@ - -

- -

doctools_plugin_apiref(n) 1.1 tcllib "Documentation tools"

Name

doctools_plugin_apiref - doctools plugin API reference

Table Of Contents
Synopsis
Description
OVERVIEW
FRONTEND COMMANDS
PLUGIN COMMANDS -
- Management commands
- Formatting commands
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

- -

Description

This document is intended for plugin writers, i.e. developers -wishing to write a doctools formatting engine for some output -format X.

It specifies the interaction between the doctools package -and its plugins, i.e. the interface any doctools formatting engine has -to comply with.

This document deals with version 1 of the interface.

A reader who is on the other hand more interested in the markup -language itself should start with the -doctools language introduction and proceed from there to the -formal specifications, i.e. the doctools language syntax and -the doctools language command reference.

OVERVIEW

The API for a doctools formatting engine consists of two major -sections.

FRONTEND COMMANDS

This section specifies the set of commands through which a plugin, -also known as a doctools formatting engine, is able to query the -frontend. These commands are provided by the frontend and linked into -the plugin interpreter.

I.e. a doctools formatting engine can assume that all of the following -commands are present when any of its own commands (as specified in -section PLUGIN COMMANDS) are executed.

dt_copyright

Query command. It returns a string containing the copyright -information the doctools processor was configured with. The relevant -option is -copyright).

dt_file

Query command. It returns the full path of the file containing the -input currently processed by the engine. This may be an included file.

dt_mainfile

Query command. It returns the full path of the toplevel file containing -the input currently processed by the engine.

dt_fileid

Query command. It returns the name of the file containing the input -currently processed by the engine, without path, nor extension.

dt_fmap symfname

Query command. It returns the actual pathname to use in the output in -place of the symbolic filename symfname. It will return the -unchanged input if no mapping was established for symfname.

The required mappings are established with the method map of -a frontend, as explained in section OBJECT METHODS -of the documentation for the package doctools.

dt_format

Query command. It returns the name of the format associated with the -doctools formatting engine.

dt_imgdata key extensions

Query command. Access to the image map. Looks for an image recorded -under the key and having on the specified extension. If a -matching image is found its data is returned as the result of the -command. Otherwise an empty string is returned.

dt_imgdst key extensions

Query command. Access to the image map. Looks for an image recorded -under the key and having on the specified extension. If a -matching image is found its destination path in the output is returned -as the result of the command. Otherwise an empty string is returned.

dt_imgsrc key extensions

Query command. Access to the image map. Looks for an image recorded -under the key and having on the specified extension. If a -matching image is found its origin path is returned as the result of -the command. Otherwise an empty string is returned.

dt_lnesting

Query command. It returns the number of lists currently open.

dt_module

Query command. It returns the name of the module the input currently -processed belongs to.

dt_read file

dt_source file

Controlled filesystem access. This command allows the doctools -formatting engine to load additional Tcl code it may need. -Only files which are either in the same directory as the file -containing the engine, or below it, can be loaded. Trying to load a -file outside of this directory causes an error.

dt_user

Query command. It returns the name of the current user as known to the -tcl interpreter the frontend controlling the formatting engine resides -in.

ex_cappend text

Appends a string to the output in the current context. This command -should rarely be used by macros or application code.

ex_cget varname

Retrieves the value of variable varname, defined in the current -context.

ex_cis cname

Determines whether or not the name of the current context is -cname.

ex_cname

Returns the name of the current context.

ex_cpop cname

Pops a context from the context stack, returning all accumulated -output in that context. The context must be named cname, or an -error results.

ex_cpush cname

Pushes a context named cname onto the context stack. The -context must be popped by cpop before expansion ends or an -error results.

ex_cset varname value

Sets variable varname to value in the current context.

ex_lb ?newbracket?

ex_rb ?newbracket?

PLUGIN COMMANDS

Management commands

The management commands a plugin has to provide are used by the -frontend to

initialize and shutdown the plugin
determine the number of passes it has - to make over the input
initialize and shutdown each pass
query and initialize engine parameters

After the plugin has been loaded and the frontend commands are -established the commands will be called in the following sequence:

-    fmt_numpasses -> n
-    fmt_listvariables -> vars
-    fmt_varset var1 value1
-    fmt_varset var2 value2
-    ...
-    fmt_varset varK valueK
-    fmt_initialize
-    fmt_setup 1
-    ...
-    fmt_setup 2
-    ...
-    ...
-    fmt_setup n
-    ...
-    fmt_postprocess
-    fmt_shutdown
-    ...
-

I.e. first the number of passes and the set of available engine -parameters is established, followed by calls setting the -parameters. That second part is optional.

In each of the passes, i.e. after the calls of fmt_setup the -frontend will process the input and call the formatting commands as -markup is encountered. This means that the sequence of formatting -commands is determined by the grammar of the doctools markup language, -as specified in the doctools language syntax specification.

A different way of looking at the sequence is:

First some basic parameters are determined.
Then everything starting at the first fmt_varset to -fmt_shutdown forms a run, the formatting of a -single input. Each run can be followed by more.
Embedded within each run we have one or more passes, -each starting with fmt_setup and going until either the next -fmt_setup or fmt_postprocess is reached.
-
If more than one pass is required to perform the formatting only the -output of the last pass is relevant. The output of all the previous, -preparatory passes is ignored.

The commands, their names, signatures, and responsibilities are, in -detail:

fmt_initialize

fmt_listvariables

Initialization/Shutdown and Engine parameters. -Second command is called after the plugin code has been loaded, -i.e. immediately after fmt_numpasses. -It has to return a list containing the names of the parameters the -frontend can set to configure the engine. This list can be empty.

fmt_numpasses

fmt_postprocess text

Expected to return a value, the final result of formatting the input.

fmt_setup n

fmt_shutdown

fmt_varset varname text

Engine parameters. -This command is called by the frontend to set an engine parameter to a -particular value. -The parameter to change is specified by varname, the value to -set in text.

The command has to throw an error if an unknown varname is -used. Only the names returned by fmt_listvariables have to be -considered as known.

The values of all engine parameters have to persist between passes and -runs.

Formatting commands

The formatting commands have to implement the formatting for the -output format, for all the markup commands of the doctools markup -language, except lb, rb, vset, include, and -comment. These exceptions are processed by the frontend and are -never seen by the plugin. In return a command for the formatting of -plain text has to be provided, something which has no markup in the -input at all.

This means, that each of the 49 markup commands specified in the -doctools language command reference and outside of the set of -exceptions listed above has an equivalent formatting command which -takes the same arguments as the markup command and whose name is the -name of markup command with the prefix fmt_ added to it.

To avoid essentially duplicating the command reference we do not list -any of the command here and simply refer the reader to the -doctools language command reference for their signature and -description. The sole exception is the plain text formatter, which has -no equivalent markup command.

The calling sequence of formatting commands is not as rigid as for the -management commands, but determined by the grammar of the doctools -markup language, as specified in the doctools language syntax -specification.

fmt_plain_text text

No associated markup command.

Called by the frontend for any plain text encountered in the -input. It has to perform any and all special processing required for -plain text.

The formatted text is expected as the result of the command, -and added to the output. If no special processing is required it has -to simply return its argument without change.

Bugs, Ideas, Feedback

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

Keywords

document, formatter, formatting engine, manpage, markup, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools/mpexpand.html Index: embedded/www/tcllib/files/modules/doctools/mpexpand.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/mpexpand.html +++ /dev/null @@ -1,199 +0,0 @@ - -

- -

mpexpand(n) 1.0 tcllib "Documentation toolbox"

Name

mpexpand - Markup processor

Table Of Contents
Synopsis
Description
NOTES
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

mpexpand ?-module module? format infile|- outfile|-
mpexpand.all ?-verbose? ?module?

Description

This manpage describes a processor / converter for manpages in the -doctools format as specified in doctools_fmt. The processor -is based upon the package doctools.

mpexpand ?-module module? format infile|- outfile|-

The processor takes three arguments, namely the code describing which -formatting to generate as the output, the file to read the markup -from, and the file to write the generated output into. If the -infile is "-" the processor will read from -stdin. If outfile is "-" the processor will -write to stdout.

If the option -module is present its value overrides the internal -definition of the module name.

The currently known output formats are

nroff: The processor generates *roff output, the standard format for unix -manpages.
html: The processor generates HTML output, for usage in and display by web -browsers.
tmml: The processor generates TMML output, the Tcl Manpage Markup Language, -a derivative of XML.
latex: The processor generates LaTeX output.
wiki: The processor generates Wiki markup as understood by wikit.
list: The processor extracts the information provided by manpage_begin.
null: The processor does not generate any output.

mpexpand.all ?-verbose? ?module?

This command uses mpexpand to generate all possible output -formats for all manpages in the current directory. The manpages are -recognized through the extension ".man". If -verbose is -specified the command will list its actions before executing them.

The module information is passed to mpexpand.

NOTES

Possible future formats are plain text, pdf and postscript.

Bugs, Ideas, Feedback

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

Keywords

HTML, TMML, conversion, manpage, markup, nroff

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2base/html_cssdefaults.html Index: embedded/www/tcllib/files/modules/doctools2base/html_cssdefaults.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2base/html_cssdefaults.html +++ /dev/null @@ -1,167 +0,0 @@ - -

- -

doctools::html::cssdefaults(n) 0.1 tcllib "Documentation tools"

Name

doctools::html::cssdefaults - Default CSS style for HTML export plugins

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::html::cssdefaults ?0.1?

::doctools::html::cssdefaults::contents

Description

This package provides a single command providing access to the text of -the default CSS style to use for HTML markup generated by the various -HTML export plugins.

This is an internal package of doctools, for use by export plugins, -i.e. the packages converting doctools related documented into other -formats, most notably HTML.

API

::doctools::html::cssdefaults::contents: This command returns the text of the default CSS style to use for HTML -markup generated by the various HTML export plugins.

Bugs, Ideas, Feedback

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

Keywords

CSS, HTML, doctools, export, plugin, style

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2base/nroff_manmacros.html Index: embedded/www/tcllib/files/modules/doctools2base/nroff_manmacros.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2base/nroff_manmacros.html +++ /dev/null @@ -1,167 +0,0 @@ - -

- -

doctools::nroff::man_macros(n) 0.1 tcllib "Documentation tools"

Name

doctools::nroff::man_macros - Default CSS style for NROFF export plugins

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::nroff::man_macros ?0.1?

::doctools::nroff::man_macros::contents

Description

This package provides a single command providing access to the -definition of the nroff man macro set to use for NROFF markup -generated by the various NROFF export plugins.

This is an internal package of doctools, for use by export plugins, -i.e. the packages converting doctools related documented into other -formats, most notably nroff.

API

::doctools::nroff::man_macros::contents: This command returns the text of the default CSS style to use for NROFF -generated by the various NROFF export plugins.

Bugs, Ideas, Feedback

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

Keywords

doctools, export, macros, man_macros, nroff, plugin

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2base/tcl_parse.html Index: embedded/www/tcllib/files/modules/doctools2base/tcl_parse.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2base/tcl_parse.html +++ /dev/null @@ -1,270 +0,0 @@ - -

- -

doctools::tcl::parse(n) 1 tcllib "Documentation tools"

Name

doctools::tcl::parse - Processing text in 'subst -novariables' format

Table Of Contents
Synopsis
Description
API
Error format
Tree Structure
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require snit
package require fileutil
package require logger
package require struct::list
package require struct::stack
package require struct::set
package require treeql
package require doctools::tcl::parse

::doctools::tcl::parse text tree text ?root?
::doctools::tcl::parse file tree path ?root?

Description

This package provides commands for parsing text with embedded Tcl -commands as accepted by the Tcl builtin command -subst -novariables. The result of the parsing is an abstract -syntax tree.

This is an internal package of doctools, for use by the higher level -parsers processing the docidx, doctoc, and doctools -markup languages.

API

::doctools::tcl::parse text tree text ?root?

The command takes the text and parses it under the assumption -that it contains a string acceptable to the Tcl builtin command -subst -novariables. Errors are thrown otherwise during the -parsing. The format used for these errors in described in section -Error format.

The command returns the empty string as it result. The actual result -of the parsing is entered into the tree structure tree, under -the node root. -If root is not specified the root of tree is used. The -tree has to exist and be the command of a tree object which -supports the same methods as trees created by the package -struct::tree.

In case of errors tree will be left in an undefined state.

::doctools::tcl::parse file tree path ?root?

The same as text, except that the text to parse is read from -the file specified by path.

Error format

When the parser encounters a problem in the input -it will throw an error using the format described -here.

The message will contain the reason for the problem (unexpected -character or end of input in input), the character in question, if -any, and the line and column the problem was found at, in a human -readable form. This part is not documented further as its format may -change as we see fit. It is intended for human consumption, not -machine.
The error code however will contain a machine-readable representation -of the problem, in the form of a 5-element list containing, in the -order listed below
-
1. the constant string doctools::tcl::parse
2. the cause of the problem, one of
  -
  -
  char
  -
  Unexpected character in input
  -
  eof
  -
  Unexpected end of the input
  -
  -
3. The location of the problem as offset from the beginning of the input, -counted in characters. Note: Line markers count as one character.
4. The line the problem was found on (counted from 1 (one)),
5. The column the problem was found at (counted from 0 (zero))
-

Tree Structure

After successfully parsing a string the generated tree will have the -following structure:

In the following items the word 'root' refers to the node which was -specified as the root of the tree when invoking either text -or file. This may be the actual root of the tree.
All the following items further ignore the possibility of pre-existing -attributes in the pre-existing nodes. If attributes exists with the -same names as the attributes used by the parser the pre-existing -values are written over. Attributes with names not clashing with the -parser's attributes are not touched.
The root node has no attributes.
All other nodes have the attributes
-
-
type
-
The value is a string from the set { Command , Text , Word }
-
range
-
The value is either empty or a 2-element list containing integer -numbers. The numbers are the offsets of the first and last character -in the input text, of the token described by the node,.
-
line
-
The value is an integer, it describes the line in the input the token -described by the node ends on. Lines are counted from 1 (one).
-
col
-
The value is an integer, it describes the column in the line in the -input the token described by the node ends on. Columns are counted -from 0 (zero).
-
-
The children of the root, if any, are of type Command and Text, in -semi-alternation. This means: After a Text node a Command node has to -follow, and anything can follow a Command node, a Text or other -Command node.
The children of a Command node, if any, are of type Command, and Text, -and Word, they describe the arguments of the command.
The children of a Word node, if any, are of type Command, Text, in -semi-alternation. This means: After a Text node a Command node has to -follow, and anything can follow a Command node, a Text or other -Command node.
A Word node without children represents the empty string.
All Text nodes are leaves of the tree.
All leaves of the tree are either Text or Command nodes. -Word nodes cannot be leaves.

Bugs, Ideas, Feedback

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

Keywords

Tcl syntax, command, doctools, parser, subst, word

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2base/tcllib_msgcat.html Index: embedded/www/tcllib/files/modules/doctools2base/tcllib_msgcat.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2base/tcllib_msgcat.html +++ /dev/null @@ -1,183 +0,0 @@ - -

- -

doctools::msgcat(n) 0.1 tcllib "Documentation tools"

Name

doctools::msgcat - Message catalog management for the various document parsers

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require msgcat
package require doctools::msgcat ?0.1?

::doctools::msgcat::init prefix

Description

The package doctools::msgcat is a support module handling -the selection of message catalogs for the various document processing -packages in the doctools system version 2. As such it is an internal -package a regular user (developer) should not be in direct contact -with.

If you are such please go the documentation of either

doctools::doc,
doctools::toc, or
doctools::idx

Within the system architecture this package resides under the various -parser packages, and is shared by them. Underneath it, but not -explicit dependencies, are the packages providing the message catalogs -for the various languages.

API

::doctools::msgcat::init prefix

The command locates and loads the message catalogs for all the -languages returned by msgcat::mcpreferences, provided that they -could be found. It returns an integer number describing how many -packages were found and loaded.

The names of the packages the command will look for have the form -"doctools::msgcat::prefix::langcode", with prefix -the argument to the command, and the langcode supplied by the -result of msgcat::mcpreferences.

Bugs, Ideas, Feedback

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

Keywords

catalog package, docidx, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/export_docidx.html Index: embedded/www/tcllib/files/modules/doctools2idx/export_docidx.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/export_docidx.html +++ /dev/null @@ -1,301 +0,0 @@ - -

- -

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

Name

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

Table Of Contents
Synopsis
Description
API
[docidx] notation of keyword indices
Configuration
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::idx::export::docidx ?0.1?

export serial configuration

Description

This package implements the doctools keyword index export plugin for -the generation of docidx markup.

This is an internal package of doctools, for use by the higher level -management packages handling keyword indices, especially doctools::idx::export, the export manager.

Using it from a regular interpreter is possible, however only with -contortions, and is not recommended. -The proper way to use this functionality is through the package -doctools::idx::export and the export manager objects it -provides.

API

The API provided by this package satisfies the specification of the -docidx export plugin API version 2.

export serial configuration: This command takes the canonical serialization of a keyword index, as -specified in section Keyword index serialization format, -and contained in serial, the configuration, a dictionary, -and generates docidx markup encoding the index. -The created string is then returned as the result of the command.

[docidx] notation of keyword indices

The docidx format for keyword indices, also called the -docidx markup language, is too large to be covered in single -section. -The interested reader should start with the document

docidx language introduction

and then proceed from there to the formal specifications, i.e. the -documents

docidx language syntax and
docidx language command reference.

to get a thorough understanding of the language.

Configuration

The docidx export plugin recognizes the following configuration -variables and changes its behaviour as they specify.

string user

This standard configuration variable contains the name of the user -running the process which invoked the export plugin. -The plugin puts this information into the provenance comment at the -beginning of the generated document.

string file

This standard configuration variable contains the name of the file the -index came from. This variable may not be set or contain the empty -string. -The plugin puts this information, if defined, i.e. set and not the -empty string, into the provenance comment at the beginning of the -generated document.

boolean newlines

If this flag is set the plugin will break the generated docidx code -across lines, with each markup command on a separate line.

If this flag is not set (the default), the whole document will be -written on a single line, with minimum spacing between all elements.

boolean indented

If this flag is set the plugin will indent the markup commands -according to the structure of indices. To make this work this also -implies that newlines is set. This effect is independent of the -value for aligned however.

If this flag is not set (the default), the output is formatted as per -the values of newlines and aligned, and no indenting is -done.

boolean aligned

If this flag is set the generator ensures that the arguments for the -manpage and url commands in a keyword section are aligned -vertically for a nice table effect. To make this work this also -implies that newlines is set. This effect is independent of the -value for indented however.

If this flag is not set (the default), the output is formatted as per -the values of newlines and indented, and no alignment is -done.

Note that this plugin ignores the standard configuration -variables format, and map, and their values.

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The canonical serialization of a keyword index has the format as -specified in the previous item, and then additionally satisfies the -constraints below, which make it unique among all the possible -serializations of the keyword index.

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

docidx, doctools, export, index, serialization

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_container.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_container.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_container.html +++ /dev/null @@ -1,445 +0,0 @@ - -

- -

doctools::idx(n) 2 tcllib "Documentation tools"

Name

doctools::idx - Holding keyword indices

Table Of Contents
Synopsis
Description
Concepts
API -
- Package commands
- Object command
- Object methods
-
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require doctools::idx ?2?
package require Tcl 8.4
package require doctools::idx::structure
package require snit

- -

Description

This package provides a class to contain and programmatically -manipulate keyword indices

This is one of the three public pillars the management of keyword -indices resides on. The other two pillars are

Exporting keyword indices, and
Importing keyword indices

For information about the Concepts of keyword indices, and -their parts, see the same-named section. -For information about the data structure which is used to encode -keyword indices as values see the section -Keyword index serialization format. -This is the only format directly known to this class. Conversions from -and to any other format are handled by export and import manager -objects. These may be attached to a container, but do not have to be, -it is merely a convenience.

Concepts

A keyword index consists of a (possibly empty) set of keywords.
Each keyword in the set is identified by its name.
Each keyword has a (possibly empty) set of references.
A reference can be associated with more than one keyword.
A reference not associated with at least one keyword is not possible -however.
Each reference is identified by its target, specified as either an url -or symbolic filename, depending on the type of reference (url, -or manpage).
The type of a reference (url, or manpage) depends only on the -reference itself, and not the keywords it is associated with.
In addition to a type each reference has a descriptive label as -well. This label depends only on the reference itself, and not the -keywords it is associated with.

A few notes

Manpage references are intended to be used for references to the -documents the index is made for. Their target is a symbolic file name -identifying the document, and export plugins may replace symbolic with -actual file names, if specified.
Url references are intended on the othre hand are inteded to be used -for links to anything else, like websites. Their target is an url.
While url and manpage references share a namespace for their -identifiers, this should be no problem, given that manpage identifiers -are symbolic filenames and as such they should never look like urls, -the identifiers for url references.

API

Package commands

::doctools::idx objectName: This command creates a new container object with an associated Tcl -command whose name is objectName. This object command is -explained in full detail in the sections Object command -and Object methods. The object command will be created -under the current namespace if the objectName is not fully -qualified, and in the specified namespace otherwise.

Object command

All objects created by the ::doctools::idx command have the -following general form:

objectName method ?arg arg ...?: The method method and its arg'uments determine the -exact behavior of the command. -See section Object methods for the detailed -specifications.

Object methods

objectName destroy

This method destroys the object it is invoked for.

objectName key add name

This method adds the keyword name to the index. If the keyword -is already known nothing is done. The result of the method is the -empty string.

objectName key remove name

This method removes the keyword name from the index. If the -keyword is already gone nothing is done. Any references for whom this -keyword was the last association are removed as well. The result of -the method is the empty string.

objectName key references name

This method returns a list containing the names of all references -associated with the keyword name. An error is thrown in the -keyword is not known to the index. The order of the references in the -list is undefined.

objectName keys

This method returns a list containing the names of all keywords known -to the index. The order of the keywords in the list is undefined.

objectName reference add type key name label

This method adds the reference name to the index and associates -it with the keyword key. -The other two arguments hold the type and label of the -reference, respectively. -The type has to match the stored information, should the reference -exist already, i.e. this information is immutable after the reference -is known. The only way to change it is delete and recreate the -reference. -The label on the other hand is automatically updated to the value of -the argument, overwriting any previously stored information. -Should the reference exists already it is simply associated with the -key. If that is true already as well nothing is done, but the -label updated to the new value. The result of the method is the -empty string.

The type argument has be to one of manpage or url.

objectName reference remove name

The reference name is removed from the index. All associations -with keywords are released and the relevant reference labels removed. -The result of the method is the empty string.

objectName reference label name

This method returns the label associated with the reference -name. An error is thrown if the reference is not known.

objectName reference keys name

This method returns a list containing the names of all keywords -associated with the reference name. An error is thrown in the -reference is not known to the index. The order of the keywords in the -list is undefined.

objectName reference type name

This method returns the type of the reference name. An error is -thrown in the reference is not known to the index.

objectName references

This method returns a list containing the names of all references -known to the index. The order of the references in the list is -undefined.

objectName title

Returns the currently defined title of the keyword index.

objectName title text

Sets the title of the keyword index to text, and returns it as -the result of the command.

objectName label

Returns the currently defined label of the keyword index.

objectName label text

Sets the label of the keyword index to text, and returns it as -the result of the command.

objectName importer

Returns the import manager object currently attached to the container, -if any.

objectName importer object

Attaches the object as import manager to the container, and -returns it as the result of the command. -Note that the object is not put into ownership of the -container. I.e., destruction of the container will not destroy -the object.

It is expected that object provides a method named -import text which takes a text and a format name, and -returns the canonical serialization of the keyword index contained in -the text, assuming the given format.

objectName exporter

Returns the export manager object currently attached to the container, -if any.

objectName exporter object

Attaches the object as export manager to the container, and -returns it as the result of the command. -Note that the object is not put into ownership of the -container. I.e., destruction of the container will not destroy -the object.

It is expected that object provides a method named -export object which takes the container and a format name, -and returns a text encoding keyword index stored in the container, in -the given format. It is further expected that the object will -use the container's method serialize to obtain the -serialization of the keyword index from which to generate the text.

objectName deserialize = data ?format?

This method replaces the contents of the index object with the index -contained in the data. If no format was specified it is -assumed to be the regular serialization of a keyword index.

Otherwise the object will use the attached import manager to convert -the data from the specified format to a serialization it can handle. -In that case an error will be thrown if the container has no import -manager attached to it.

The result of the method is the empty string.

objectName deserialize += data ?format?

This method behaves like deserialize = in its essentials, -except that it merges the keyword index in the data to its -contents instead of replacing it. -The method will throw an error if merging is not possible, i.e. would -produce an invalid index. The existing content is left unchanged in -that case.

The result of the method is the empty string.

objectName serialize ?format?

This method returns the keyword index contained in the object. If no -format is not specified the returned result is the canonical -serialization of its contents.

Otherwise the object will use the attached export manager to convert -the data to the specified format. -In that case an error will be thrown if the container has no export -manager attached to it.

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

HTML, TMML, conversion, docidx markup, documentation, formatting, generation, index, json, keyword index, latex, manpage, markup, nroff, parsing, plugin, reference, tcler's wiki, text, url, wiki

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_export.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_export.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_export.html +++ /dev/null @@ -1,459 +0,0 @@ - -

- -

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

Name

doctools::idx::export - Exporting keyword indices

Table Of Contents
Synopsis
Description
Concepts
API -
- Package commands
- Object command
- Object methods
-
Export plugin API v2 reference
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require doctools::idx::export ?0.2?
package require Tcl 8.4
package require doctools::config
package require doctools::idx::structure
package require snit
package require pluginmgr

::doctools::idx::export objectName
objectName method ?arg arg ...?
objectName destroy
objectName export serial serial ?format?
objectName export object object ?format?
objectName config names
objectName config get
objectName config set name ?value?
objectName config unset pattern...
export serial configuration

Description

This package provides a class to manage the plugins for the export of -keyword indices to other formats, i.e. their conversion to, for -example docidx, HTML, etc.

This is one of the three public pillars the management of keyword -indices resides on. The other two pillars are

Importing keyword indices, and
Holding keyword indices

For information about the Concepts of keyword indices, and -their parts, see the same-named section. -For information about the data structure which is the major input to -the manager objects provided by this package see the section -Keyword index serialization format.

The plugin system of our class is based on the package -pluginmgr, and configured to look for plugins using

the environment variable DOCTOOLS_IDX_EXPORT_PLUGINS,
the environment variable DOCTOOLS_IDX_PLUGINS,
the environment variable DOCTOOLS_PLUGINS,
the path "~/.doctools/idx/export/plugin"
the path "~/.doctools/idx/plugin"
the path "~/.doctools/plugin"
the path "~/.doctools/idx/export/plugins"
the path "~/.doctools/idx/plugins"
the path "~/.doctools/plugins"
the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\EXPORT\PLUGINS"
the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\PLUGINS"
the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

The last three are used only when the package is run on a machine -using Windows(tm) operating system.

The whole system is delivered with six predefined export plugins, -namely

docidx: See docidx export plugin for details.
html: See html export plugin for details.
json: See json export plugin for details.
nroff: See nroff export plugin for details.
text: See text export plugin for details.
wiki: See wiki export plugin for details.

Readers wishing to write their own export plugin for some format, i.e. -plugin writers reading and understanding the section -containing the Export plugin API v2 reference is an -absolute necessity, as it specifies the interaction between this -package and its plugins in detail.

Concepts

A keyword index consists of a (possibly empty) set of keywords.
Each keyword in the set is identified by its name.
Each keyword has a (possibly empty) set of references.
A reference can be associated with more than one keyword.
A reference not associated with at least one keyword is not possible -however.
Each reference is identified by its target, specified as either an url -or symbolic filename, depending on the type of reference (url, -or manpage).
The type of a reference (url, or manpage) depends only on the -reference itself, and not the keywords it is associated with.
In addition to a type each reference has a descriptive label as -well. This label depends only on the reference itself, and not the -keywords it is associated with.

A few notes

Manpage references are intended to be used for references to the -documents the index is made for. Their target is a symbolic file name -identifying the document, and export plugins may replace symbolic with -actual file names, if specified.
Url references are intended on the othre hand are inteded to be used -for links to anything else, like websites. Their target is an url.
While url and manpage references share a namespace for their -identifiers, this should be no problem, given that manpage identifiers -are symbolic filenames and as such they should never look like urls, -the identifiers for url references.

API

Package commands

::doctools::idx::export objectName: This command creates a new export manager object with an associated -Tcl command whose name is objectName. This object command -is explained in full detail in the sections Object command -and Object methods. The object command will be created -under the current namespace if the objectName is not fully -qualified, and in the specified namespace otherwise.

Object command

All objects created by the ::doctools::idx::export command have -the following general form:

objectName method ?arg arg ...?: The method method and its arg'uments determine the -exact behavior of the command. -See section Object methods for the detailed -specifications.

Object methods

objectName destroy

This method destroys the object it is invoked for.

objectName export serial serial ?format?

This method takes the canonical serialization of a keyword index -stored in serial and converts it to the specified format, -using the export plugin for the format. An error is thrown if no -plugin could be found for the format. -The string generated by the conversion process is returned as -the result of this method.

If no format is specified the method defaults to docidx.

The specification of what a canonical serialization is can be -found in the section Keyword index serialization format.

The plugin has to conform to the interface specified in section -Export plugin API v2 reference.

objectName export object object ?format?

This method is a convenient wrapper around the export serial -method described by the previous item. -It expects that object is an object command supporting a -serialize method returning the canonical serialization of a -keyword index. It invokes that method, feeds the result into -export serial and returns the resulting string as its own -result.

objectName config names

This method returns a list containing the names of all configuration -variables currently known to the object.

objectName config get

This method returns a dictionary containing the names and values of -all configuration variables currently known to the object.

objectName config set name ?value?

This method sets the configuration variable name to the -specified value and returns the new value of the variable.

If no value is specified it simply returns the current value, without -changing it.

Note that while the user can set the predefined configuration -variables user and format doing so will have no -effect, these values will be internally overridden when invoking an -import plugin.

objectName config unset pattern...

This method unsets all configuration variables matching the specified -glob patterns. If no pattern is specified it will unset all -currently defined configuration variables.

Export plugin API v2 reference

Plugins are what this package uses to manage the support for any -output format beyond the -Keyword index serialization format. Here we specify the -API the objects created by this package use to interact with their -plugins.

A plugin for this package has to follow the rules listed below:

A plugin is a package.
The name of a plugin package has the form - doctools::idx::export::FOO, - where FOO is the name of the format the plugin will - generate output for. This name is also the argument to provide - to the various export methods of export manager - objects to get a string encoding a keyword index in that - format.
The plugin can expect that the package - doctools::idx::export::plugin is present, as - indicator that it was invoked from a genuine plugin manager.
A plugin has to provide one command, with the signature shown - below.
-
-
export serial configuration
-
Whenever an export manager of doctools::idx has to generate -output for an index it will invoke this command.
-
-
string serial
-
This argument will contain the canonical serialization of the -index for which to generate the output. -The specification of what a canonical serialization is can be -found in the section Keyword index serialization format.
-
dictionary configuration
-
This argument will contain the current configuration to apply to the -generation, as a dictionary mapping from variable names to values.
-
The following configuration variables have a predefined meaning all -plugins have to obey, although they can ignore this information at -their discretion. Any other other configuration variables recognized -by a plugin will be described in the manpage for that plugin.
-
-
user
-
This variable is expected to contain the name of the user - owning the process invoking the plugin.
-
format
-
This variable is expected to contain the name of the - format whose plugin is invoked.
-
file
-
This variable, if defined by the user of the index object - is expected to contain the name of the input file for which - the plugin is generating its output for.
-
map
-
This variable, if defined by the user of the index object is - expected to contain a dictionary mapping from symbolic file - names used in the references of type manpage to - actual paths (or urls). A plugin has to be able to handle - the possibility that a symbolic name is without entry in - this mapping.
-
-
-
-
A single usage cycle of a plugin consists of the invokations of - the command export. This call has to leave the plugin in - a state where another usage cycle can be run without problems.

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

HTML, conversion, docidx, documentation, export, formatting, generation, index, json, keyword index, manpage, markup, nroff, plugin, reference, tcler's wiki, text, url, wiki

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_export_html.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_export_html.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_export_html.html +++ /dev/null @@ -1,363 +0,0 @@ - -

- -

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

Name

doctools::idx::export::html - HTML export plugin

Table Of Contents
Synopsis
Description
API
Configuration
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::idx::export::html ?0.2?
package require doctools::text
package require doctools::html
package require doctools::html::cssdefaults

export serial configuration

Description

This package implements the doctools keyword index export plugin for -the generation of HTML markup.

This is an internal package of doctools, for use by the higher level -management packages handling keyword indices, especially doctools::idx::export, the export manager.

API

The API provided by this package satisfies the specification of the -docidx export plugin API version 2.

export serial configuration: This command takes the canonical serialization of a keyword index, as -specified in section Keyword index serialization format, -and contained in serial, the configuration, a dictionary, -and generates HTML markup encoding the index. -The created string is then returned as the result of the command.

Configuration

The html export plugin recognizes the following configuration -variables and changes its behaviour as they specify.

string user

string file

dictionary map

This standard configuration variable contains a dictionary mapping -from the symbolic files names in manpage references to the actual -filenames and/or urls to be used in the output.

Url references and symbolic file names without a mapping are used -unchanged.

boolean newlines

If this flag is set the plugin will break the generated html code -across lines, with each markup command on a separate line.

If this flag is not set (the default), the whole document will be -written on a single line, with minimum spacing between all elements.

boolean indented

If this flag is set the plugin will indent the markup commands -according to the structure of indices. To make this work this also -implies that newlines is set.

If this flag is not set (the default), the output is formatted as per -the value of newlines, and no indenting is done.

string meta

This variable is meant to hold a fragment of HTML (default: empty). -The fragment it contains will be inserted into the generated output in -the <head> section of the document, just after the <title> tag.

string header

This variable is meant to hold a fragment of HTML (default: empty). -The fragment it contains will be inserted into the generated output -just after the <h1> title tag in the body of the document, in the -class.header <div>'ision.

string footer

This variable is meant to hold a fragment of HTML (default: -empty). The fragment it contains will be inserted into the generated -output just before the </body> tag, in the class.footer <div>'ision.

dictionary kwid

The value of this variable (default: empty) maps keywords to the -identifiers to use as their anchor names. Each keyword FOO not -found in the dictionary uses KW-FOO as anchor, -i.e. itself prefixed with the string KW-.

string sepline

The value of this variable is the string to use for the separator -comments inserted into the output when the outpout is broken across -lines and/or indented. The default string consists of 60 dashes.

integer kwidth

This variable holds the size of the keyword column in the main table -generated by the plugin, in percent of the total width of the -table. This is an integer number in the range of 1 to 99. Choosing a -value outside of that range causes the generator to switch back to the -defauly setting, 35 percent.

string dot

This variable contains a HTML fragment inserted between the entries of -the navigation bar, and the references associated with each keyword. -The default is the HTML entity · i.e. the bullet character, also -known as the "Greek middle dot", i.e. the unicode character 00B7.

string class.main

This variable contains the class name for the main <div>'ivision of -the generated document. The default is doctools.

string class.header

This variable contains the class name for the header <div>'ision of -the generated document. The default is idx-header. This -division contains the document title, the user specified header, -if any, a visible separator line, and the navigation bar for quick -access to each keyword section.

string class.title

This variable contains the class name for the <h1> tag enclosing the -document title. The default is idx-title.

string class.navsep

This variable contains the class name for the <hr> separators in the -header and footer sections of the generated document. The default is -idx-navsep.

string class.navbar

This variable contains the class name for the navigation <div>'ision -enclosing the navigation bar of the generated document. The default is -idx-kwnav.

string class.contents

This variable contains the class name for the <table> holding the -keywords and their references in the generated document. The default -is idx-contents.

string class.leader

This variable contains the class name for the anchor names the plugin -inserts into the keyword table when switching from one section to the -next (Each section holds all keywords with a particular first -character). The default is idx-leader.

string class.row0

This variable contains the class name used to label the even rows -(<tr>) of the keyword table. The default is idx-even.

string class.row1

This variable contains the class name used to label the odd rows -(<tr>) of the keyword table. The default is idx-odd.

string class.keyword

This variable contains the class name used to label the keyword -cells/column (<td>) in the keyword table of the document. The default -is idx-keyword.

string class.refs

This variable contains the class name used to label the reference -cells/column (<td>) in the keyword table of the document. The default -is idx-refs.

string class.footer

This variable contains the class name for the footer <div>'ision of -the generated document. The default is idx-footer. This -division contains a browser-visible separator line and the user -specified footer, if any.

Note that this plugin ignores the standard configuration -variable format, and its value.

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

HTML, doctools, export, index, serialization

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_export_json.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_export_json.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_export_json.html +++ /dev/null @@ -1,316 +0,0 @@ - -

- -

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

Name

doctools::idx::export::json - JSON export plugin

Table Of Contents
Synopsis
Description
API
JSON notation of keyword indices
Configuration
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::idx::export::json ?0.1?
package require textutil::adjust

export serial configuration

Description

This package implements the doctools keyword index export plugin for -the generation of JSON markup.

This is an internal package of doctools, for use by the higher level -management packages handling keyword indices, especially doctools::idx::export, the export manager.

API

The API provided by this package satisfies the specification of the -docidx export plugin API version 2.

export serial configuration: This command takes the canonical serialization of a keyword index, as -specified in section Keyword index serialization format, -and contained in serial, the configuration, a dictionary, -and generates JSON markup encoding the index. -The created string is then returned as the result of the command.

JSON notation of keyword indices

The JSON format used for keyword indices is a direct translation of -the Keyword index serialization format, mapping Tcl -dictionaries as JSON objects and Tcl lists as JSON arrays. -For example, the Tcl serialization

-doctools::idx {
-	label {Keyword Index}
-	keywords {
-		changelog  {changelog.man cvs.man}
-		conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man}
-		cvs        cvs.man
-	}
-	references {
-		apps/dtplite.man {manpage dtplite}
-		changelog.man    {manpage doctools::changelog}
-		cvs.man          {manpage doctools::cvs}
-		docidx.man       {manpage doctools::idx}
-		doctoc.man       {manpage doctools::toc}
-		doctools.man     {manpage doctools}
-		mpexpand.man     {manpage mpexpand}
-	}
-	title {}
-}
-

is equivalent to the JSON string

-{
-    "doctools::idx" : {
-        "label"      : "Keyword Index",
-        "keywords"   : {
-            "changelog"  : ["changelog.man","cvs.man"],
-            "conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"],
-            "cvs"        : ["cvs.man"],
-        },
-        "references" : {
-            "apps\/dtplite.man" : ["manpage","dtplite"],
-            "changelog.man"     : ["manpage","doctools::changelog"],
-            "cvs.man"           : ["manpage","doctools::cvs"],
-            "docidx.man"        : ["manpage","doctools::idx"],
-            "doctoc.man"        : ["manpage","doctools::toc"],
-            "doctools.man"      : ["manpage","doctools"],
-            "mpexpand.man"      : ["manpage","mpexpand"]
-        },
-        "title"      : ""
-    }
-}
-

Configuration

The JSON export plugin recognizes the following configuration -variables and changes its behaviour as they specify.

boolean indented

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

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

boolean aligned

If this flag is set the generator ensures that the values for the keys -in a dictionary are vertically aligned with each other, for a nice -table effect. To make this work this also implies that indented -is set.

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

Note that this plugin ignores the standard configuration -variables user, format, file, and map and -their values.

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

JSON, doctools, export, index, serialization

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_export_nroff.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_export_nroff.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_export_nroff.html +++ /dev/null @@ -1,270 +0,0 @@ - -

- -

doctools::idx::export::nroff(n) 0.3 tcllib "Documentation tools"

Name

doctools::idx::export::nroff - nroff export plugin

Table Of Contents
Synopsis
Description
API
Configuration
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::idx::export::nroff ?0.3?
package require doctools::text
package require doctools::nroff::man_macros

export serial configuration

Description

This package implements the doctools keyword index export plugin for -the generation of nroff markup.

This is an internal package of doctools, for use by the higher level -management packages handling keyword indices, especially doctools::idx::export, the export manager.

API

The API provided by this package satisfies the specification of the -docidx export plugin API version 2.

export serial configuration: This command takes the canonical serialization of a keyword index, as -specified in section Keyword index serialization format, -and contained in serial, the configuration, a dictionary, -and generates nroff markup encoding the index. -The created string is then returned as the result of the command.

Configuration

The nroff export plugin recognizes the following configuration -variables and changes its behaviour as they specify.

string user

string file

boolean inline

If this flag is set (default) the plugin will place the definitions of -the man macro set directly into the output.

If this flag is not set, the plugin will place a reference to the -definitions of the man macro set into the output, but not the macro -definitions themselves.

Note that this plugin ignores the standard configuration -variables format, and map, and their values.

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

doctools, export, index, nroff, serialization

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_export_text.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_export_text.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_export_text.html +++ /dev/null @@ -1,257 +0,0 @@ - -

- -

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

Name

doctools::idx::export::text - plain text export plugin

Table Of Contents
Synopsis
Description
API
Configuration
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::idx::export::text ?0.2?
package require doctools::text

export serial configuration

Description

This package implements the doctools keyword index export plugin for -the generation of plain text markup.

This is an internal package of doctools, for use by the higher level -management packages handling keyword indices, especially doctools::idx::export, the export manager.

API

The API provided by this package satisfies the specification of the -docidx export plugin API version 2.

export serial configuration: This command takes the canonical serialization of a keyword index, as -specified in section Keyword index serialization format, -and contained in serial, the configuration, a dictionary, -and generates plain text markup encoding the index. -The created string is then returned as the result of the command.

Configuration

The text export plugin recognizes the following configuration -variables and changes its behaviour as they specify.

dictionary map

This standard configuration variable contains a dictionary mapping -from the symbolic files names in manpage references to the actual -filenames and/or urls to be used in the output.

Url references and symbolic file names without a mapping are used -unchanged.

Note that this plugin ignores the standard configuration -variables user, file, and format, and their values.

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

doctools, export, index, plain text, serialization

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_export_wiki.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_export_wiki.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_export_wiki.html +++ /dev/null @@ -1,270 +0,0 @@ - -

- -

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

Name

doctools::idx::export::wiki - wiki export plugin

Table Of Contents
Synopsis
Description
API
Wiki markup
Configuration
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::idx::export::wiki ?0.2?
package require doctools::text

export serial configuration

Description

This package implements the doctools keyword index export plugin for -the generation of wiki markup.

This is an internal package of doctools, for use by the higher level -management packages handling keyword indices, especially doctools::idx::export, the export manager.

API

The API provided by this package satisfies the specification of the -docidx export plugin API version 2.

export serial configuration: This command takes the canonical serialization of a keyword index, as -specified in section Keyword index serialization format, -and contained in serial, the configuration, a dictionary, -and generates wiki markup encoding the index. -The created string is then returned as the result of the command.

Wiki markup

The basic syntax of the wiki markup generated by this plugin are -described at http://wiki.tcl.tk/14.

The plugin goes beyond the classic markup to generate proper headers -and either a table or indented list of the keywords and their -references.

Configuration

The wiki export plugin recognizes the following configuration -variables and changes its behaviour as they specify.

dictionary map

This standard configuration variable contains a dictionary mapping -from the symbolic files names in manpage references to the actual -filenames and/or urls to be used in the output.

Url references and symbolic file names without a mapping are used -unchanged.

enum style

This variable recognizes two values as legal, list (default), -and table. -Depending on the value the plugin generates either a list- or -table-based wiki page for the index.

Note that this plugin ignores the standard configuration -variables user, file and format, and their values.

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

doctools, export, index, serialization, wiki

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_import.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_import.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_import.html +++ /dev/null @@ -1,518 +0,0 @@ - -

- -

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

Name

doctools::idx::import - Importing keyword indices

Table Of Contents
Synopsis
Description
Concepts
API -
- Package commands
- Object command
- Object methods
-
Import plugin API v2 reference
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require doctools::idx::import ?0.2?
package require Tcl 8.4
package require doctools::config
package require doctools::idx::structure
package require snit
package require pluginmgr

::doctools::idx::import objectName
objectName method ?arg arg ...?
objectName destroy
objectName import text text ?format?
objectName import file path ?format?
objectName import object text object text ?format?
objectName import object file object path ?format?
objectName config names
objectName config get
objectName config set name ?value?
objectName config unset pattern...
objectName includes
objectName include add path
objectName include remove path
objectName include clear
IncludeFile currentfile path
import text configuration

Description

This package provides a class to manage the plugins for the import of -keyword indices from other formats, i.e. their conversion from, for -example docidx, json, etc.

This is one of the three public pillars the management of keyword -indices resides on. The other two pillars are

Exporting keyword indices, and
Holding keyword indices

For information about the Concepts of keyword indices, and -their parts, see the same-named section. -For information about the data structure which is the major output of -the manager objects provided by this package see the section -Keyword index serialization format.

The plugin system of our class is based on the package -pluginmgr, and configured to look for plugins using

the environment variable DOCTOOLS_IDX_IMPORT_PLUGINS,
the environment variable DOCTOOLS_IDX_PLUGINS,
the environment variable DOCTOOLS_PLUGINS,
the path "~/.doctools/idx/import/plugin"
the path "~/.doctools/idx/plugin"
the path "~/.doctools/plugin"
the path "~/.doctools/idx/import/plugins"
the path "~/.doctools/idx/plugins"
the path "~/.doctools/plugins"
the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\IMPORT\PLUGINS"
the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\PLUGINS"
the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

The last three are used only when the package is run on a machine -using Windows(tm) operating system.

The whole system is delivered with two predefined import plugins, -namely

docidx: See docidx import plugin for details.
json: See json import plugin for details.

Readers wishing to write their own import plugin for some format, i.e. -plugin writers reading and understanding the section -containing the Import plugin API v2 reference is an -absolute necessity, as it specifies the interaction between this -package and its plugins in detail.

Concepts

A keyword index consists of a (possibly empty) set of keywords.
Each keyword in the set is identified by its name.
Each keyword has a (possibly empty) set of references.
A reference can be associated with more than one keyword.
A reference not associated with at least one keyword is not possible -however.
Each reference is identified by its target, specified as either an url -or symbolic filename, depending on the type of reference (url, -or manpage).
The type of a reference (url, or manpage) depends only on the -reference itself, and not the keywords it is associated with.
In addition to a type each reference has a descriptive label as -well. This label depends only on the reference itself, and not the -keywords it is associated with.

A few notes

Manpage references are intended to be used for references to the -documents the index is made for. Their target is a symbolic file name -identifying the document, and export plugins may replace symbolic with -actual file names, if specified.
Url references are intended on the othre hand are inteded to be used -for links to anything else, like websites. Their target is an url.
While url and manpage references share a namespace for their -identifiers, this should be no problem, given that manpage identifiers -are symbolic filenames and as such they should never look like urls, -the identifiers for url references.

API

Package commands

::doctools::idx::import objectName: This command creates a new import manager object with an associated -Tcl command whose name is objectName. This object command -is explained in full detail in the sections Object command -and Object methods. The object command will be created -under the current namespace if the objectName is not fully -qualified, and in the specified namespace otherwise.

Object command

All objects created by the ::doctools::idx::import command have -the following general form:

objectName method ?arg arg ...?: The method method and its arg'uments determine the -exact behavior of the command. -See section Object methods for the detailed -specifications.

Object methods

objectName destroy

This method destroys the object it is invoked for.

objectName import text text ?format?

This method takes the text and converts it from the specified -format to the canonical serialization of a keyword index using -the import plugin for the format. An error is thrown if no plugin -could be found for the format. -The serialization generated by the conversion process is returned as -the result of this method.

If no format is specified the method defaults to docidx.

The specification of what a canonical serialization is can be -found in the section Keyword index serialization format.

The plugin has to conform to the interface specified in section -Import plugin API v2 reference.

objectName import file path ?format?

This method is a convenient wrapper around the import text -method described by the previous item. -It reads the contents of the specified file into memory, feeds the -result into import text and returns the resulting -serialization as its own result.

objectName import object text object text ?format?

This method is a convenient wrapper around the import text -method described by the previous item. -It expects that object is an object command supporting a -deserialize method expecting the canonical serialization of a -keyword index. -It imports the text using import text and then feeds the -resulting serialization into the object via deserialize. -This method returns the empty string as it result.

objectName import object file object path ?format?

This method behaves like import object text, except that it -reads the text to convert from the specified file instead of being -given it as argument.

objectName config names

This method returns a list containing the names of all configuration -variables currently known to the object.

objectName config get

This method returns a dictionary containing the names and values of -all configuration variables currently known to the object.

objectName config set name ?value?

This method sets the configuration variable name to the -specified value and returns the new value of the variable.

If no value is specified it simply returns the current value, without -changing it.

objectName config unset pattern...

This method unsets all configuration variables matching the specified -glob patterns. If no pattern is specified it will unset all -currently defined configuration variables.

objectName includes

This method returns a list containing the currently specified paths to -use to search for include files when processing input. -The order of paths in the list corresponds to the order in which they -are used, from first to last, and also corresponds to the order in -which they were added to the object.

objectName include add path

This methods adds the specified path to the list of paths to use -to search for include files when processing input. The path is added -to the end of the list, causing it to be searched after all previously -added paths. The result of the command is the empty string.

The method does nothing if the path is already known.

objectName include remove path

This methods removes the specified path from the list of paths -to use to search for include files when processing input. The result -of the command is the empty string.

The method does nothing if the path is not known.

objectName include clear

This method clears the list of paths to use to search for include -files when processing input. The result of the command is the empty -string.

Import plugin API v2 reference

Plugins are what this package uses to manage the support for any input -format beyond the Keyword index serialization format. Here -we specify the API the objects created by this package use to interact -with their plugins.

A plugin for this package has to follow the rules listed below:

A plugin is a package.
The name of a plugin package has the form - doctools::idx::import::FOO, - where FOO is the name of the format the plugin will - generate output for. This name is also the argument to provide - to the various import methods of import manager - objects to get a string encoding a keyword index in that - format.
The plugin can expect that the package - doctools::idx::export::plugin is present, as - indicator that it was invoked from a genuine plugin manager.
The plugin can expect that a command named IncludeFile is - present, with the signature
-
-
IncludeFile currentfile path
-
This command has to be invoked by the plugin when it has to process an -included file, if the format has the concept of such. An example of -such a format would be docidx.
-
The plugin has to supply the following arguments
-
-
string currentfile
-
The path of the file it is currently processing. This may be the empty -string if no such is known.
-
string path
-
The path of the include file as specified in the include directive -being processed.
-
-
The result of the command will be a 5-element list containing
-
1. A boolean flag indicating the success (True) or failure - (False) of the operation.
2. In case of success the contents of the included file, and the - empty string otherwise.
3. The resolved, i.e. absolute path of the included file, if - possible, or the unchanged path argument. This is for - display in an error message, or as the currentfile - argument of another call to IncludeFile should this file - contain more files.
4. In case of success an empty string, and for failure a code - indicating the reason for it, one of
  -
  -
  notfound
  -
  The specified file could not be found.
  -
  notread
  -
  The specified file was found, but not be read into memory.
  -
  -
5. An empty string in case of success of a notfound - failure, and an additional error message describing the reason - for a notread error in more detail.
-
-
A plugin has to provide one command, with the signature shown - below.
-
-
import text configuration
-
Whenever an import manager of doctools::idx has to parse -input for an index it will invoke this command.
-
-
string text
-
This argument will contain the text encoding the index per the format -the plugin is for.
-
dictionary configuration
-
This argument will contain the current configuration to apply to the -parsing, as a dictionary mapping from variable names to values.
-
The following configuration variables have a predefined meaning all -plugins have to obey, although they can ignore this information at -their discretion. Any other other configuration variables recognized -by a plugin will be described in the manpage for that plugin.
-
-
user
-
This variable is expected to contain the name of the user - owning the process invoking the plugin.
-
format
-
This variable is expected to contain the name of the - format whose plugin is invoked.
-
-
-
-
A single usage cycle of a plugin consists of the invokations of - the command import. This call has to leave the plugin in - a state where another usage cycle can be run without problems.

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

conversion, docidx, documentation, import, index, json, keyword index, manpage, markup, parsing, plugin, reference, url

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_import_json.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_import_json.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_import_json.html +++ /dev/null @@ -1,293 +0,0 @@ - -

- -

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

Name

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

Table Of Contents
Synopsis
Description
API
JSON notation of keyword indices
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::idx::import::json ?0.1?
package require doctools::idx::structure
package require json

import string configuration

Description

This package implements the doctools keyword index import plugin for -the parsing of JSON markup.

This is an internal package of doctools, for use by the higher level -management packages handling keyword indices, especially doctools::idx::import, the import manager.

Using it from a regular interpreter is possible, however only with -contortions, and is not recommended. -The proper way to use this functionality is through the package -doctools::idx::import and the import manager objects it -provides.

API

The API provided by this package satisfies the specification of the -docidx import plugin API version 2.

import string configuration: This command takes the string and parses it as JSON -markup encoding a keyword index, in the context of the specified -configuration (a dictionary). The result of the command is the -canonical serialization of that keyword index, in the form specified -in section Keyword index serialization format.

JSON notation of keyword indices

-doctools::idx {
-	label {Keyword Index}
-	keywords {
-		changelog  {changelog.man cvs.man}
-		conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man}
-		cvs        cvs.man
-	}
-	references {
-		apps/dtplite.man {manpage dtplite}
-		changelog.man    {manpage doctools::changelog}
-		cvs.man          {manpage doctools::cvs}
-		docidx.man       {manpage doctools::idx}
-		doctoc.man       {manpage doctools::toc}
-		doctools.man     {manpage doctools}
-		mpexpand.man     {manpage mpexpand}
-	}
-	title {}
-}
-

is equivalent to the JSON string

-{
-    "doctools::idx" : {
-        "label"      : "Keyword Index",
-        "keywords"   : {
-            "changelog"  : ["changelog.man","cvs.man"],
-            "conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"],
-            "cvs"        : ["cvs.man"],
-        },
-        "references" : {
-            "apps\/dtplite.man" : ["manpage","dtplite"],
-            "changelog.man"     : ["manpage","doctools::changelog"],
-            "cvs.man"           : ["manpage","doctools::cvs"],
-            "docidx.man"        : ["manpage","doctools::idx"],
-            "doctoc.man"        : ["manpage","doctools::toc"],
-            "doctools.man"      : ["manpage","doctools"],
-            "mpexpand.man"      : ["manpage","mpexpand"]
-        },
-        "title"      : ""
-    }
-}
-

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

JSON, deserialization, doctools, import, index

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_introduction.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_introduction.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_introduction.html +++ /dev/null @@ -1,257 +0,0 @@ - -

- -

doctools2idx_introduction(n) 2.0 tcllib "Documentation tools"

Name

doctools2idx_introduction - DocTools - Keyword indices

Table Of Contents
Description
Related formats
Package Overview
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

docidx (short for documentation indices) stands for a -set of related, yet different, entities which are working together for -the easy creation and transformation of keyword indices for -documentation.

These are

A tcl based language for the semantic markup of a keyword index. -Markup is represented by Tcl commands. -Beginners should start with the -docidx language introduction. -The formal specification is split over two documents, one dealing with -the docidx language syntax, the other a -docidx language command reference.
A set of packages for the programmatic manipulation of keyword indices -in memory, and their conversion between various formats, reading and -writing. The aforementioned markup language is one of the formats -which can be both read from and written to.
The system for the conversion of indices is based on a plugin -mechanism, for this we have two APIs describing the interface between -the packages above and the import/export plugins.

Which of the more detailed documents are relevant to the reader of -this introduction depends on their role in the documentation process.

A writer of documentation has to understand the markup language -itself. A beginner to docidx should read the more informally written -docidx language introduction first. Having digested this -the formal docidx language syntax specification should -become understandable. A writer experienced with docidx may only -need the docidx language command reference from time to -time to refresh her memory.
-
While a document is written the dtp application can be used -to validate it, and after completion it also performs the conversion -into the chosen system of visual markup, be it *roff, HTML, plain -text, wiki, etc. The simpler dtplite application makes -internal use of docidx when handling directories of documentation, -automatically generating a proper keyword index for them.
A processor of documentation written in the docidx -markup language has to know which tools are available for use.
-
The main tool is the aforementioned dtp application provided -by Tcllib. The simpler dtplite does not expose docidx to the -user. At the bottom level, common to both applications, however we -find the three packages providing the basic facilities to handle -keyword indices, i.e. import from textual formats, programmatic -manipulation in memory, and export to textual formats. These are
-
-
doctools::idx
-
Programmatic manipulation of keyword indices in memory.
-
doctools::idx::import
-
Import of keyword indices from various textual formats. The set of -supported formats is extensible through plugin packages.
-
doctools::idx::export
-
Export of keyword indices to various textual formats. The set of -supported formats is extensible through plugin packages.
-
-
See also section Package Overview for an overview of the -dependencies between these and other, supporting packages.
At last, but not least, plugin writers have to understand the -interaction between the import and export packages and their plugins. -These APIs are described in the documentation for the two relevant -packages, i.e.
-
- doctools::idx::import
- doctools::idx::export
-

Related formats

The docidx format does not stand alone, it has two companion formats. -These are called doctoc and doctools, and they are -intended for the markup of tables of contents, and of general -documentation, respectively. -They are described in their own sets of documents, starting at -the DocTools - Tables Of Contents and -the DocTools - General, respectively.

Package Overview

-                                    ~~~~~~~~~~~ doctools::idx ~~~~~~~~~~~
-                                   ~~                   |               ~~
-                doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import
-                        |                               |                       |
-        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
-        |               |                         |     |    |                  |               |                       |               |
-doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
-                        |                         |     |    |                  |
-                doctools::idx::export::<*>        |     |    |          doctools::idx::import::<*>
-                        docidx                    |     |    |                  docidx, json
-                        json                      |     |    |                  |           \\
-                        html                      |     |    |          doctools::idx::parse \\
-                        nroff                     |     |    |                  |             \\
-                        wiki                      |     |    |  +---------------+              json
-                        text                      |     |    |  |               |
-                                                doctools::idx::structure        |
-                                                                                |
-                                                                        +-------+---------------+
-                                                                        |                       |
-          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat        
-                |                                                                               |
-          doctools::text  doctools::nroff::man_macros                                           =
-                                                                                                |
-                                                                                        doctools::msgcat::idx::<*>
-                                                                                                c, en, de, fr
-                                                                                                (fr == en for now)
-        ~~      Interoperable objects, without actual package dependencies
-        --      Package dependency, higher requires lower package
-        =       Dynamic dependency through plugin system
-        <*>     Multiple packages following the given form of naming.
-

Bugs, Ideas, Feedback

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

Keywords

conversion, formatting, index, keyword index, markup, parsing, plugin, semantic markup

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_c.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_c.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_c.html +++ /dev/null @@ -1,171 +0,0 @@ - -

- -

doctools::msgcat::idx::c(n) 0.1 tcllib "Documentation tools"

Name

doctools::msgcat::idx::c - Message catalog for the docidx parser (C)

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require msgcat
package require doctools::msgcat::idx::c ?0.1?

Description

The package doctools::msgcat::idx::c is a -support module providing the C language message catalog -for the docidx parser in the doctools system version 2. As such it is -an internal package a regular user (developer) should not be in direct -contact with.

If you are such please go the documentation of either

doctools::doc,
doctools::toc, or
doctools::idx

Within the system architecture this package resides under the package -doctools::msgcat providing the general message catalog -management within the system. Note that there is no -explicit dependency between the manager and catalog packages. The -catalog is a plugin which is selected and loaded dynamically.

API

This package has no exported API.

Bugs, Ideas, Feedback

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

Keywords

C, catalog package, docidx, doctools, i18n, internationalization, l10n, localization, message catalog, message package

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_de.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_de.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_de.html +++ /dev/null @@ -1,171 +0,0 @@ - -

- -

doctools::msgcat::idx::de(n) 0.1 tcllib "Documentation tools"

Name

doctools::msgcat::idx::de - Message catalog for the docidx parser (DE)

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require msgcat
package require doctools::msgcat::idx::de ?0.1?

Description

The package doctools::msgcat::idx::de is a -support module providing the DE (german) language message catalog -for the docidx parser in the doctools system version 2. As such it is -an internal package a regular user (developer) should not be in direct -contact with.

If you are such please go the documentation of either

doctools::doc,
doctools::toc, or
doctools::idx

API

This package has no exported API.

Bugs, Ideas, Feedback

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

Keywords

DE, catalog package, docidx, doctools, i18n, internationalization, l10n, localization, message catalog, message package

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_en.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_en.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_en.html +++ /dev/null @@ -1,171 +0,0 @@ - -

- -

doctools::msgcat::idx::en(n) 0.1 tcllib "Documentation tools"

Name

doctools::msgcat::idx::en - Message catalog for the docidx parser (EN)

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require msgcat
package require doctools::msgcat::idx::en ?0.1?

Description

The package doctools::msgcat::idx::en is a -support module providing the EN (english) language message catalog -for the docidx parser in the doctools system version 2. As such it is -an internal package a regular user (developer) should not be in direct -contact with.

If you are such please go the documentation of either

doctools::doc,
doctools::toc, or
doctools::idx

API

This package has no exported API.

Bugs, Ideas, Feedback

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

Keywords

EN, catalog package, docidx, doctools, i18n, internationalization, l10n, localization, message catalog, message package

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_fr.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_fr.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_fr.html +++ /dev/null @@ -1,171 +0,0 @@ - -

- -

doctools::msgcat::idx::fr(n) 0.1 tcllib "Documentation tools"

Name

doctools::msgcat::idx::fr - Message catalog for the docidx parser (FR)

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require msgcat
package require doctools::msgcat::idx::fr ?0.1?

Description

The package doctools::msgcat::idx::fr is a -support module providing the FR (french) language message catalog -for the docidx parser in the doctools system version 2. As such it is -an internal package a regular user (developer) should not be in direct -contact with.

If you are such please go the documentation of either

doctools::doc,
doctools::toc, or
doctools::idx

API

This package has no exported API.

Bugs, Ideas, Feedback

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

Keywords

FR, catalog package, docidx, doctools, i18n, internationalization, l10n, localization, message catalog, message package

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_parse.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_parse.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_parse.html +++ /dev/null @@ -1,347 +0,0 @@ - -

- -

doctools::idx::parse(n) 1 tcllib "Documentation tools"

Name

doctools::idx::parse - Parsing text in docidx format

Table Of Contents
Synopsis
Description
API
Parse errors
[docidx] notation of keyword indices
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require doctools::idx::parse ?0.1?
package require Tcl 8.4
package require doctools::idx::structure
package require doctools::msgcat
package require doctools::tcl::parse
package require fileutil
package require logger
package require snit
package require struct::list
package require struct::stack

::doctools::idx::parse text text
::doctools::idx::parse file path
::doctools::idx::parse includes
::doctools::idx::parse include add path
::doctools::idx::parse include remove path
::doctools::idx::parse include clear
::doctools::idx::parse vars
::doctools::idx::parse var set name value
::doctools::idx::parse var unset name
::doctools::idx::parse var clear ?pattern?

Description

This package provides commands to parse text written in the -docidx markup language and convert it into the canonical -serialization of the keyword index encoded in the text. -See the section Keyword index serialization format for -specification of their format.

This is an internal package of doctools, for use by the higher level -packages handling docidx documents.

API

::doctools::idx::parse text text

The command takes the string contained in text and parses it -under the assumption that it contains a document written using the -docidx markup language. An error is thrown if this assumption -is found to be false. The format of these errors is described in -section Parse errors.

When successful the command returns the canonical serialization of the -keyword index which was encoded in the text. -See the section Keyword index serialization format for -specification of that format.

::doctools::idx::parse file path

The same as text, except that the text to parse is read from -the file specified by path.

::doctools::idx::parse includes

This method returns the current list of search paths used when looking -for include files.

::doctools::idx::parse include add path

This method adds the path to the list of paths searched when -looking for an include file. The call is ignored if the path is -already in the list of paths. The method returns the empty string as -its result.

::doctools::idx::parse include remove path

This method removes the path from the list of paths searched -when looking for an include file. The call is ignored if the path is -not contained in the list of paths. The method returns the empty -string as its result.

::doctools::idx::parse include clear

This method clears the list of search paths for include files.

::doctools::idx::parse vars

This method returns a dictionary containing the current set of -predefined variables known to the vset markup command during -processing.

::doctools::idx::parse var set name value

This method adds the variable name to the set of predefined -variables known to the vset markup command during processing, -and gives it the specified value. The method returns the empty -string as its result.

::doctools::idx::parse var unset name

This method removes the variable name from the set of predefined -variables known to the vset markup command during -processing. The method returns the empty string as its result.

::doctools::idx::parse var clear ?pattern?

This method removes all variables matching the pattern from the -set of predefined variables known to the vset markup command -during processing. The method returns the empty string as its result.

The pattern matching is done with string match, and the -default pattern used when none is specified, is *.

Parse errors

The format of the parse error messages thrown when encountering -violations of the docidx markup syntax is human readable and -not intended for processing by machines. As such it is not documented.

However, the errorCode attached to the message is -machine-readable and has the following format:

The error code will be a list, each element describing a single error -found in the input. The list has at least one element, possibly more.
Each error element will be a list containing six strings describing an -error in detail. The strings will be
-
1. The path of the file the error occurred in. This may be empty.
2. The range of the token the error was found at. This range is a -two-element list containing the offset of the first and last character -in the range, counted from the beginning of the input (file). Offsets -are counted from zero.
3. The line the first character after the error is on. -Lines are counted from one.
4. The column the first character after the error is at. -Columns are counted from zero.
5. The message code of the error. This value can be used as argument to -msgcat::mc to obtain a localized error message, assuming that -the application had a suitable call of doctools::msgcat::init to -initialize the necessary message catalogs (See package -doctools::msgcat).
6. A list of details for the error, like the markup command involved. In -the case of message code docidx/include/syntax this value is -the set of errors found in the included file, using the format -described here.
-

[docidx] notation of keyword indices

The docidx format for keyword indices, also called the -docidx markup language, is too large to be covered in single -section. -The interested reader should start with the document

docidx language introduction

and then proceed from there to the formal specifications, i.e. the -documents

docidx language syntax and
docidx language command reference.

to get a thorough understanding of the language.

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

docidx, doctools, lexer, parser

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/idx_structure.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_structure.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_structure.html +++ /dev/null @@ -1,288 +0,0 @@ - -

- -

doctools::idx::structure(n) 0.1 tcllib "Documentation tools"

Name

doctools::idx::structure - Docidx serialization utilities

Table Of Contents
Synopsis
Description
API
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require doctools::idx::structure ?0.1?
package require Tcl 8.4
package require logger
package require snit

::doctools::idx::structure verify serial ?canonvar?
::doctools::idx::structure verify-as-canonical serial
::doctools::idx::structure canonicalize serial
::doctools::idx::structure print serial
::doctools::idx::structure merge seriala serialb

Description

This package provides commands to work with the serializations of -keyword indices as managed by the doctools system v2, and specified in -section Keyword index serialization format.

This is an internal package of doctools, for use by the higher level -packages handling keyword indices and their conversion into and out of -various other formats, like documents written using docidx -markup.

API

::doctools::idx::structure verify serial ?canonvar?

This command verifies that the content of serial is a valid -regular serialization of a keyword index and will throw an -error if that is not the case. The result of the command is the empty -string.

If the argument canonvar is specified it is interpreted as the -name of a variable in the calling context. This variable will be -written to if and only if serial is a valid regular -serialization. Its value will be a boolean, with True -indicating that the serialization is not only valid, but also -canonical. False will be written for a valid, but -non-canonical serialization.

For the specification of regular and canonical keyword index -serializations see the section -Keyword index serialization format.

::doctools::idx::structure verify-as-canonical serial

This command verifies that the content of serial is a valid -canonical serialization of a keyword index and will throw an -error if that is not the case. The result of the command is the empty -string.

For the specification of canonical keyword index serializations see -the section Keyword index serialization format.

::doctools::idx::structure canonicalize serial

This command assumes that the content of serial is a valid -regular serialization of a keyword index and will throw an -error if that is not the case.

It will then convert the input into the canonical serialization -of the contained keyword index and return it as its result. If the -input is already canonical it will be returned unchanged.

For the specification of regular and canonical keyword index -serializations see the section -Keyword index serialization format.

::doctools::idx::structure print serial

This command assumes that the argument serial contains a valid -regular serialization of a keyword index and returns a string -containing that index in a human readable form.

The exact format of this form is not specified and cannot be relied on -for parsing or other machine-based activities.

For the specification of regular keyword index serializations see the -section Keyword index serialization format.

::doctools::idx::structure merge seriala serialb

This command accepts the regular serializations of two keyword indices -and uses them to create their union. The result of the command is the -canonical serialization of this unified keyword index.

Title and label of the resulting index are taken from the index -contained in serialb. The set of keys, references and their -connections is the union of the set of keys and references of the two -inputs.

For the specification of regular and canonical keyword index -serializations see the section -Keyword index serialization format.

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

deserialization, docidx, doctools, serialization

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2idx/import_docidx.html Index: embedded/www/tcllib/files/modules/doctools2idx/import_docidx.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/import_docidx.html +++ /dev/null @@ -1,270 +0,0 @@ - -

- -

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

Name

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

Table Of Contents
Synopsis
Description
API
[docidx] notation of keyword indices
Keyword index serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::idx::import::docidx ?0.1?
package require doctools::idx::parse
package require doctools::idx::structure
package require doctools::msgcat
package require doctools::tcl::parse
package require fileutil
package require logger
package require snit
package require struct::list
package require struct::set
package require struct::stack
package require struct::tree
package require treeql

import string configuration

Description

This package implements the doctools keyword index import plugin for -the parsing of docidx markup.

This is an internal package of doctools, for use by the higher level -management packages handling keyword indices, especially doctools::idx::import, the import manager.

Using it from a regular interpreter is possible, however only with -contortions, and is not recommended. -The proper way to use this functionality is through the package -doctools::idx::import and the import manager objects it -provides.

API

The API provided by this package satisfies the specification of the -docidx import plugin API version 2.

import string configuration: This command takes the string and parses it as docidx -markup encoding a keyword index, in the context of the specified -configuration (a dictionary). The result of the command is the -canonical serialization of that keyword index, in the form specified -in section Keyword index serialization format.

[docidx] notation of keyword indices

The docidx format for keyword indices, also called the -docidx markup language, is too large to be covered in single -section. -The interested reader should start with the document

docidx language introduction

and then proceed from there to the formal specifications, i.e. the -documents

docidx language syntax and
docidx language command reference.

to get a thorough understanding of the language.

Keyword index serialization format

Here we specify the format used by the doctools v2 packages to -serialize keyword indices as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. While a keyword index may have more than one regular -serialization only exactly one of them will be canonical.

regular serialization

An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, doctools::idx, and its -value. This value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of -the index, a label, and the keywords and references. The relevant keys -and their values are
-
-
title
-
The value is a string containing the title of the index.
-
label
-
The value is a string containing a label for the index.
-
keywords
-
The value is a Tcl dictionary, using the keywords known to the index -as keys. The associated values are lists containing the identifiers of -the references associated with that particular keyword.
-
Any reference identifier used in these lists has to exist as a key in -the references dictionary, see the next item for its -definition.
-
references
-
The value is a Tcl dictionary, using the identifiers for the -references known to the index as keys. The associated values are -2-element lists containing the type and label of the reference, in -this order.
-
Any key here has to be associated with at least one keyword, -i.e. occur in at least one of the reference lists which are the values -in the keywords dictionary, see previous item for its -definition.
-
-
The type of a reference can be one of two values,
-
-
manpage
-
The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for.
-
url
-
The identifier of the reference is interpreted as an url, referring to -some external location, like a website, etc.
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.
The references listed for each keyword of the index, if any, are -listed in ascending dictionary order of their labels, as -generated by Tcl's builtin command lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

deserialization, docidx, doctools, import, index

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/export_doctoc.html Index: embedded/www/tcllib/files/modules/doctools2toc/export_doctoc.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/export_doctoc.html +++ /dev/null @@ -1,324 +0,0 @@ - -

- -

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

Name

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

Table Of Contents
Synopsis
Description
API
[doctoc] notation of tables of contents
Configuration
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::toc::export::doctoc ?0.1?

export serial configuration

Description

This package implements the doctools table of contents export plugin -for the generation of doctoc markup.

This is an internal package of doctools, for use by the higher level -management packages handling tables of contents, especially doctools::toc::export, the export manager.

Using it from a regular interpreter is possible, however only with -contortions, and is not recommended. -The proper way to use this functionality is through the package -doctools::toc::export and the export manager objects it -provides.

API

The API provided by this package satisfies the specification of the -doctoc export plugin API version 2.

export serial configuration: This command takes the canonical serialization of a table of contents, -as specified in section ToC serialization format, and -contained in serial, the configuration, a dictionary, and -generates doctoc markup encoding the table. -The created string is then returned as the result of the command.

[doctoc] notation of tables of contents

The doctoc format for tables of contents, also called the -doctoc markup language, is too large to be covered in single -section. -The interested reader should start with the document

doctoc language introduction

and then proceed from there to the formal specifications, i.e. the -documents

doctoc language syntax and
doctoc language command reference.

to get a thorough understanding of the language.

Configuration

The doctoc export plugin recognizes the following configuration -variables and changes its behaviour as they specify.

string user

string file

This standard configuration variable contains the name of the file the -table of contents came from. This variable may not be set or contain -the empty string. -The plugin puts this information, if defined, i.e. set and not the -empty string, into the provenance comment at the beginning of the -generated document.

boolean newlines

If this flag is set the plugin will break the generated doctoc code -across lines, with each markup command on a separate line.

If this flag is not set (the default), the whole document will be -written on a single line, with minimum spacing between all elements.

boolean indented

If this flag is set the plugin will indent the markup commands -according to the structure of tables of contents. To make this work -this also implies that newlines is set. This effect is -independent of the value for aligned however.

If this flag is not set (the default), the output is formatted as per -the value of newlines, and no indenting is done.

boolean aligned

If this flag is set the generator ensures that the arguments for the -item commands in a division are aligned vertically for a nice -table effect. To make this work this also implies that newlines -is set. This effect is independent of the value for indented -however.

If this flag is not set (the default), the output is formatted as per -the values of newlines and indented, and no alignment is -done.

Note that this plugin ignores the standard configuration -variables format, and map, and their values.

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The canonical serialization of a table of contents has the format as -specified in the previous item, and then additionally satisfies the -constraints below, which make it unique among all the possible -serializations of this table of contents.

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

doctoc, doctools, export, serialization, table of contents, toc

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/import_doctoc.html Index: embedded/www/tcllib/files/modules/doctools2toc/import_doctoc.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/import_doctoc.html +++ /dev/null @@ -1,294 +0,0 @@ - -

- -

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

Name

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

Table Of Contents
Synopsis
Description
API
[doctoc] notation of tables of contents
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::toc::import::doctoc ?0.1?
package require doctools::toc::parse
package require doctools::toc::structure
package require doctools::msgcat
package require doctools::tcl::parse
package require fileutil
package require logger
package require snit
package require struct::list
package require struct::set
package require struct::stack
package require struct::tree
package require treeql

import string configuration

Description

This package implements the doctools table of contents import plugin -for the parsing of doctoc markup.

This is an internal package of doctools, for use by the higher level -management packages handling tables of contents, especially doctools::toc::import, the import manager.

Using it from a regular interpreter is possible, however only with -contortions, and is not recommended. -The proper way to use this functionality is through the package -doctools::toc::import and the import manager objects it -provides.

API

The API provided by this package satisfies the specification of the -doctoc import plugin API version 2.

import string configuration: This command takes the string and parses it as doctoc -markup encoding a table of contents, in the context of the specified -configuration (a dictionary). The result of the command is the -canonical serialization of that table of contents, in the form -specified in section ToC serialization format.

[doctoc] notation of tables of contents

The doctoc format for tables of contents, also called the -doctoc markup language, is too large to be covered in single -section. -The interested reader should start with the document

doctoc language introduction

and then proceed from there to the formal specifications, i.e. the -documents

doctoc language syntax and
doctoc language command reference.

to get a thorough understanding of the language.

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

deserialization, doctoc, doctools, import, table of contents, toc

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_container.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_container.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_container.html +++ /dev/null @@ -1,510 +0,0 @@ - -

- -

doctools::toc(n) 2 tcllib "Documentation tools"

Name

doctools::toc - Holding tables of contents

Table Of Contents
Synopsis
Description
Concepts
API -
- Package commands
- Object command
- Object methods
-
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require doctools::toc ?2?
package require Tcl 8.4
package require doctools::toc::structure
package require struct::tree
package require snit

- -

Description

This package provides a class to contain and programmatically -manipulate tables of contents.

This is one of the three public pillars the management of tables of -contents resides on. The other two pillars are

Exporting tables of contents, and
Importing tables of contents

For information about the Concepts of tables of contents, and -their parts, see the same-named section. -For information about the data structure which is used to encode -tables of contents as values see the section -ToC serialization format. -This is the only format directly known to this class. Conversions from -and to any other format are handled by export and import manager -objects. These may be attached to a container, but do not have to be, -it is merely a convenience.

Concepts

A table of contents consists of a (possibly empty) list of -elements.
Each element in the list is identified by its label.
Each element is either a reference, or a division.
Each reference has an associated document, identified by a symbolic -id, and a textual description.
Each division may have an associated document, identified by a -symbolic id.
Each division consists consists of a (possibly empty) list of -elements, with each element following the rules as specified in -item 2 and above.

A few notes

The above rules span up a tree of elements, with references as the -leaf nodes, and divisions as the inner nodes, and each element -representing an entry in the whole table of contents.
The identifying labels of any element E are unique within their -division (or toc), and the full label of any element E is the list of -labels for all nodes on the unique path from the root of the tree to -E, including E.

API

Package commands

::doctools::toc objectName: This command creates a new container object with an associated Tcl -command whose name is objectName. This object command is -explained in full detail in the sections Object command -and Object methods. The object command will be created -under the current namespace if the objectName is not fully -qualified, and in the specified namespace otherwise.

Object command

All objects created by the ::doctools::toc command have the -following general form:

objectName method ?arg arg ...?: The method method and its arg'uments determine the -exact behavior of the command. -See section Object methods for the detailed -specifications.

Object methods

objectName destroy

This method destroys the object it is invoked for.

objectName + reference id label docid desc

This method adds a new reference element to the table of contents, -under the element specified via its handle id. This parent -element has to be a division element, or the root. An error is thrown -otherwise. -The new element will be externally identified by its label, -which has to be be unique within the parent element. An error is -thrown otherwise.

As a reference element it will refer to a document identified by the -symbolic docid. This reference must not be the empty string, an -error is thrown otherwise. -Beyond the label the element also has a longer descriptive string, -supplied via desc.

The result of the method is the handle (id) of the new element.

objectName + division id label ?docid?

This method adds a new division element to the table of contents, -under the element specified via its handle id. This parent -element has to be a division element, or the root. An error is thrown -otherwise. -The new element will be externally identified by its label, -which has to be be unique within the parent element. An error is -thrown otherwise.

As a division element it is can refer to a document, identified by the -symbolic docid, but may choose not to.

The result of the method is the handle (id) of the new element.

objectName remove id

This method removes the element identified by the handle id from -the table of contents. -If the element is a division all of its children, if any, are removed -as well. The root element/division of the table of contents cannot be -removed however, only its children.

The result of the method is the empty string.

objectName up id

This method returns the handle of the parent for the element -identified by its handle id, or the empty string if id -referred to the root element.

objectName next id

This method returns the handle of the right sibling for the element -identified by its handle id, or the handle of the parent if the -element has no right sibling, or the empty string if id referred -to the root element.

objectName prev id

This method returns the handle of the left sibling for the element -identified by its handle id, or the handle of the parent if the -element has no left sibling, or the empty string if id referred -to the root element.

objectName child id label ?...?

This method returns the handle of a child of the element identified by -its handle id. The child itself is identified by a series of -labels.

objectName element ?...?

This method returns the handle of the element identified by a series -of labels, starting from the root of the table of contents. The series -of labels is allowed to be empty, in which case the handle of the root -element is returned.

objectName children id

This method returns a list containing the handles of all children of -the element identified by the handle id, from first to last, in -that order.

objectName type id

This method returns the type of the element, either reference, -or division.

objectName full-label id

This method is the complement of the method element, -converting the handle id of an element into a list of labels -full identifying the element within the whole table of contents.

objectName elabel id ?newlabel?

This method queries and/or changes the label of the element identified -by the handle id. If the argument newlabel is present then -the label is changed to that value. Regardless of this, the result of -the method is the current value of the label.

If the label is changed the new label has to be unique within the -containing division, or an error is thrown.

Further, of the id refers to the root element of the table of -contents, then using this method is equivalent to using the method -label, i.e. it is accessing the global label for the whole -table.

objectName description id ?newdesc?

This method queries and/or changes the description of the element -identified by the handle id. If the argument newdesc is -present then the description is changed to that value. Regardless of -this, the result of the method is the current value of the description.

The element this method operates on has to be a reference element, or -an error will be thrown.

objectName document id ?newdocid?

This method queries and/or changes the document reference of the -element identified by the handle id. -If the argument newdocid is present then the description is -changed to that value. Regardless of this, the result of the method is -the current value of the document reference.

Setting the reference to the empty string means unsetting it, and is -allowed only for division elements. Conversely, if the result is the -empty string then the element has no document reference, and this can -happen only for division elements.

objectName title

Returns the currently defined title of the table of contents.

objectName title text

Sets the title of the table of contents to text, and returns it as -the result of the command.

objectName label

Returns the currently defined label of the table of contents.

objectName label text

Sets the label of the table of contents to text, and returns it as -the result of the command.

objectName importer

Returns the import manager object currently attached to the container, -if any.

objectName importer object

It is expected that object provides a method named -import text which takes a text and a format name, and -returns the canonical serialization of the table of contents contained in -the text, assuming the given format.

objectName exporter

Returns the export manager object currently attached to the container, -if any.

objectName exporter object

It is expected that object provides a method named -export object which takes the container and a format name, -and returns a text encoding table of contents stored in the container, in -the given format. It is further expected that the object will -use the container's method serialize to obtain the -serialization of the table of contents from which to generate the text.

objectName deserialize = data ?format?

This method replaces the contents of the table object with the table -contained in the data. If no format was specified it is -assumed to be the regular serialization of a table of contents.

The result of the method is the empty string.

objectName deserialize += data ?format?

This method behaves like deserialize = in its essentials, -except that it merges the table of contents in the data to its -contents instead of replacing it. -The method will throw an error if merging is not possible, i.e. would -produce an invalid table. The existing content is left unchanged in -that case.

The result of the method is the empty string.

objectName serialize ?format?

This method returns the table of contents contained in the object. If no -format is not specified the returned result is the canonical -serialization of its contents.

Otherwise the object will use the attached export manager to convert -the data to the specified format. -In that case an error will be thrown if the container has no export -manager attached to it.

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

HTML, TMML, conversion, doctoc markup, documentation, formatting, generation, json, latex, markup, nroff, parsing, plugin, reference, table, table of contents, tcler's wiki, text, wiki

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_export.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_export.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_export.html +++ /dev/null @@ -1,475 +0,0 @@ - -

- -

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

Name

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

Table Of Contents
Synopsis
Description
Concepts
API -
- Package commands
- Object command
- Object methods
-
Export plugin API v2 reference
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require doctools::toc::export ?0.2?
package require Tcl 8.4
package require doctools::config
package require doctools::toc::structure
package require snit
package require pluginmgr

::doctools::toc::export objectName
objectName method ?arg arg ...?
objectName destroy
objectName export serial serial ?format?
objectName export object object ?format?
objectName config names
objectName config get
objectName config set name ?value?
objectName config unset pattern...
export serial configuration

Description

This package provides a class to manage the plugins for the export of -tables of contents to other formats, i.e. their conversion to, for -example doctoc, HTML, etc.

This is one of the three public pillars the management of tables of -contents resides on. The other two pillars are

Importing tables of contents, and
Holding tables of contents

For information about the Concepts of tables of contents, -and their parts, see the same-named section. -For information about the data structure which is the major input to -the manager objects provided by this package see the section -ToC serialization format.

The plugin system of our class is based on the package -pluginmgr, and configured to look for plugins using

the environment variable DOCTOOLS_TOC_EXPORT_PLUGINS,
the environment variable DOCTOOLS_TOC_PLUGINS,
the environment variable DOCTOOLS_PLUGINS,
the path "~/.doctools/toc/export/plugin"
the path "~/.doctools/toc/plugin"
the path "~/.doctools/plugin"
the path "~/.doctools/toc/export/plugins"
the path "~/.doctools/toc/plugins"
the path "~/.doctools/plugins"
the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\EXPORT\PLUGINS"
the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\PLUGINS"
the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

The last three are used only when the package is run on a machine -using Windows(tm) operating system.

The whole system is delivered with six predefined export plugins, -namely

doctoc: See doctoc export plugin for details.
html: See html export plugin for details.
json: See json export plugin for details.
nroff: See nroff export plugin for details.
text: See text export plugin for details.
wiki: See wiki export plugin for details.

Concepts

A table of contents consists of a (possibly empty) list of -elements.
Each element in the list is identified by its label.
Each element is either a reference, or a division.
Each reference has an associated document, identified by a symbolic -id, and a textual description.
Each division may have an associated document, identified by a -symbolic id.
Each division consists consists of a (possibly empty) list of -elements, with each element following the rules as specified in -item 2 and above.

A few notes

The above rules span up a tree of elements, with references as the -leaf nodes, and divisions as the inner nodes, and each element -representing an entry in the whole table of contents.
The identifying labels of any element E are unique within their -division (or toc), and the full label of any element E is the list of -labels for all nodes on the unique path from the root of the tree to -E, including E.

API

Package commands

::doctools::toc::export objectName: This command creates a new export manager object with an associated -Tcl command whose name is objectName. This object command -is explained in full detail in the sections Object command -and Object methods. The object command will be created -under the current namespace if the objectName is not fully -qualified, and in the specified namespace otherwise.

Object command

All objects created by the ::doctools::toc::export command have -the following general form:

objectName method ?arg arg ...?: The method method and its arg'uments determine the -exact behavior of the command. -See section Object methods for the detailed -specifications.

Object methods

objectName destroy

This method destroys the object it is invoked for.

objectName export serial serial ?format?

This method takes the canonical serialization of a table of contents -stored in serial and converts it to the specified format, -using the export plugin for the format. An error is thrown if no -plugin could be found for the format. -The string generated by the conversion process is returned as -the result of this method.

If no format is specified the method defaults to doctoc.

The specification of what a canonical serialization is can be -found in the section ToC serialization format.

The plugin has to conform to the interface specified in section -Export plugin API v2 reference.

objectName export object object ?format?

This method is a convenient wrapper around the export serial -method described by the previous item. -It expects that object is an object command supporting a -serialize method returning the canonical serialization of a -table of contents. It invokes that method, feeds the result into -export serial and returns the resulting string as its own -result.

objectName config names

This method returns a list containing the names of all configuration -variables currently known to the object.

objectName config get

This method returns a dictionary containing the names and values of -all configuration variables currently known to the object.

objectName config set name ?value?

This method sets the configuration variable name to the -specified value and returns the new value of the variable.

If no value is specified it simply returns the current value, without -changing it.

objectName config unset pattern...

This method unsets all configuration variables matching the specified -glob patterns. If no pattern is specified it will unset all -currently defined configuration variables.

Export plugin API v2 reference

Plugins are what this package uses to manage the support for any -output format beyond the ToC serialization format. Here we -specify the API the objects created by this package use to interact -with their plugins.

A plugin for this package has to follow the rules listed below:

A plugin is a package.
The name of a plugin package has the form - doctools::toc::export::FOO, - where FOO is the name of the format the plugin will - generate output for. This name is also the argument to provide - to the various export methods of export manager - objects to get a string encoding a table of contents in that - format.
The plugin can expect that the package - doctools::toc::export::plugin is present, as - indicator that it was invoked from a genuine plugin manager.
A plugin has to provide one command, with the signature shown - below.
-
-
export serial configuration
-
Whenever an export manager of doctools::toc has to generate -output for a table of contents it will invoke this command.
-
-
string serial
-
This argument will contain the canonical serialization of the -table of contents for which to generate the output. -The specification of what a canonical serialization is can be -found in the section ToC serialization format.
-
dictionary configuration
-
This argument will contain the current configuration to apply to the -generation, as a dictionary mapping from variable names to values.
-
The following configuration variables have a predefined meaning all -plugins have to obey, although they can ignore this information at -their discretion. Any other other configuration variables recognized -by a plugin will be described in the manpage for that plugin.
-
-
user
-
This variable is expected to contain the name of the user - owning the process invoking the plugin.
-
format
-
This variable is expected to contain the name of the - format whose plugin is invoked.
-
file
-
This variable, if defined by the user of the table object - is expected to contain the name of the input file for which - the plugin is generating its output for.
-
map
-
This variable, if defined by the user of the table object is - expected to contain a dictionary mapping from symbolic - document ids used in the table entries to actual paths (or - urls). A plugin has to be able to handle the possibility - that a document id is without entry in this mapping.
-
-
-
-
A single usage cycle of a plugin consists of the invokations of - the command export. This call has to leave the plugin in - a state where another usage cycle can be run without problems.

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

HTML, conversion, doctoc, documentation, export, formatting, generation, json, manpage, markup, nroff, plugin, reference, table, table of contents, tcler's wiki, text, url, wiki

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_export_html.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_export_html.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_export_html.html +++ /dev/null @@ -1,357 +0,0 @@ - -

- -

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

Name

doctools::toc::export::html - HTML export plugin

Table Of Contents
Synopsis
Description
API
Configuration
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::toc::export::html ?0.1?
package require doctools::text
package require doctools::html
package require doctools::html::cssdefaults

export serial configuration

Description

This package implements the doctools table of contents export plugin -for the generation of HTML markup.

This is an internal package of doctools, for use by the higher level -management packages handling tables of contents, especially doctools::toc::export, the export manager.

Using it from a regular interpreter is possible, however only with -contortions, and is not recommended. -The proper way to use this functionality is through the package -doctools::toc::export and the export manager objects it -provides.

API

The API provided by this package satisfies the specification of the -doctoc export plugin API version 2.

export serial configuration: This command takes the canonical serialization of a table of contents, -as specified in section ToC serialization format, and -contained in serial, the configuration, a dictionary, and -generates HTML markup encoding the table. -The created string is then returned as the result of the command.

Configuration

The html export plugin recognizes the following configuration -variables and changes its behaviour as they specify.

string user

string file

dictionary map

This standard configuration variable contains a dictionary mapping -from the (symbolic) document ids in reference entries to the actual -filenames and/or urls to be used in the output.

Document ids without a mapping are used unchanged.

boolean newlines

If this flag is set the plugin will break the generated html code -across lines, with each markup command on a separate line.

If this flag is not set (the default), the whole document will be -written on a single line, with minimum spacing between all elements.

boolean indented

If this flag is set the plugin will indent the markup commands -according to the structure of indices. To make this work this also -implies that newlines is set.

If this flag is not set (the default), the output is formatted as per -the value of newlines, and no indenting is done.

string meta

string header

string footer

This variable is meant to hold a fragment of HTML (default: -empty). The fragment it contains will be inserted into the generated -output just before the </body> tag, in the class.footer <div>'ision.

dictionary rid

The value of this variable (default: empty) maps references to the -identifiers to use as their anchor names. Each reference FOO not -found in the dictionary uses REF-FOO as anchor, -i.e. itself prefixed with the string REF-.

string sepline

string class.main

This variable contains the class name for the main <div>'ivision of -the generated document. The default is doctools.

string class.header

This variable contains the class name for the header <div>'ision of -the generated document. The default is toc-header. This -division contains the document title, the user specified header, -if any, and a visible separator line.

string class.title

This variable contains the class name for the <h1> tag enclosing the -document title. The default is toc-title.

string class.navsep

This variable contains the class name for the <hr> separators in the -header and footer sections of the generated document. The default is -toc-navsep.

string class.contents

This variable contains the class name for the XXXXX holding the -keywords and their references in the generated document. The default -is toc-contents.

string class.ref

This variable contains the class name for the table elements which are -references to other documents. The default is toc-ref.

string class.div

This variable contains the class name for the table elements which are -divisions. The default is toc-div.

string class.footer

This variable contains the class name for the footer <div>'ision of -the generated document. The default is toc-footer. This -division contains a browser-visible separator line and the user -specified footer, if any.

Note that this plugin ignores the standard configuration -variable format, and its value.

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

HTML, doctools, export, serialization, table of contents, toc

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_export_json.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_export_json.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_export_json.html +++ /dev/null @@ -1,360 +0,0 @@ - -

- -

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

Name

doctools::toc::export::json - JSON export plugin

Table Of Contents
Synopsis
Description
API
JSON notation of tables of contents
Configuration
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::toc::export::json ?0.1?
package require textutil::adjust

export serial configuration

Description

This package implements the doctools table of contents export plugin -for the generation of JSON markup.

This is an internal package of doctools, for use by the higher level -management packages handling tables of contents, especially doctools::toc::export, the export manager.

Using it from a regular interpreter is possible, however only with -contortions, and is not recommended. -The proper way to use this functionality is through the package -doctools::toc::export and the export manager objects it -provides.

API

The API provided by this package satisfies the specification of the -doctoc export plugin API version 2.

export serial configuration: This command takes the canonical serialization of a table of contents, -as specified in section ToC serialization format, and -contained in serial, the configuration, a dictionary, and -generates JSON markup encoding the table. -The created string is then returned as the result of the command.

JSON notation of tables of contents

The JSON format used for tables of contents is a direct translation of -the ToC serialization format, mapping Tcl dictionaries as -JSON objects and Tcl lists as JSON arrays. -For example, the Tcl serialization

-doctools::toc {
-    items {
-        {reference {
-	    desc {DocTools - Tables of Contents}
-	     id introduction.man
-	     label doctools::toc::introduction
-	}}
-	{division {
-	     id processing.man
-	     items {
-	         {reference {
-		     desc {doctoc serialization utilities}
-		     id structure.man
-		     label doctools::toc::structure
-		 }}
-		 {reference {
-		     desc {Parsing text in doctoc format}
-		     id parse.man
-		     label doctools::toc::parse
-		 }}
-	     }
-             label Processing
-        }}
-    }
-    label {Table of Contents} 
-    title TOC
-}
-

is equivalent to the JSON string

-{
-    "doctools::toc" : {
-        "items" : [{
-            "reference" : {
-                "desc"  : "DocTools - Tables of Contents",
-                "id"    : "introduction.man",
-                "label" : "doctools::toc::introduction"
-            }
-        },{
-            "division" : {
-                "id"    : "processing.man",
-                "items" : [{
-                    "reference" : {
-                        "desc"  : "doctoc serialization utilities",
-                        "id"    : "structure.man",
-                        "label" : "doctools::toc::structure"
-                    }
-                },{
-                    "reference" : {
-                        "desc"  : "Parsing text in doctoc format",
-                        "id"    : "parse.man",
-                        "label" : "doctools::toc::parse"
-                    }
-                }],
-                "label" : "Processing"
-            }
-        }],
-        "label" : "Table of Contents",
-        "title" : "TOC"
-    }
-}
-

Configuration

The JSON export plugin recognizes the following configuration -variables and changes its behaviour as they specify.

boolean indented

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

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

boolean aligned

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

Note that this plugin ignores the standard configuration -variables user, format, file, and map and -their values.

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

JSON, doctools, export, serialization, table of contents, toc

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_export_nroff.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_export_nroff.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_export_nroff.html +++ /dev/null @@ -1,294 +0,0 @@ - -

- -

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

Name

doctools::toc::export::nroff - nroff export plugin

Table Of Contents
Synopsis
Description
API
Configuration
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::toc::export::nroff ?0.2?
package require doctools::text
package require doctools::nroff::man_macros

export serial configuration

Description

This package implements the doctools table of contents export plugin -for the generation of nroff markup.

This is an internal package of doctools, for use by the higher level -management packages handling tables of contents, especially doctools::toc::export, the export manager.

Using it from a regular interpreter is possible, however only with -contortions, and is not recommended. -The proper way to use this functionality is through the package -doctools::toc::export and the export manager objects it -provides.

API

The API provided by this package satisfies the specification of the -doctoc export plugin API version 2.

export serial configuration: This command takes the canonical serialization of a table of contents, -as specified in section ToC serialization format, and -contained in serial, the configuration, a dictionary, and -generates nroff markup encoding the table. -The created string is then returned as the result of the command.

Configuration

The nroff export plugin recognizes the following configuration -variables and changes its behaviour as they specify.

string user

string file

boolean inline

If this flag is set (default) the plugin will place the definitions of -the man macro set directly into the output.

If this flag is not set, the plugin will place a reference to the -definitions of the man macro set into the output, but not the macro -definitions themselves.

Note that this plugin ignores the standard configuration -variables format, and map, and their values.

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

doctools, export, nroff, serialization, table of contents, toc

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_export_text.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_export_text.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_export_text.html +++ /dev/null @@ -1,280 +0,0 @@ - -

- -

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

Name

doctools::toc::export::text - plain text export plugin

Table Of Contents
Synopsis
Description
API
Configuration
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::toc::export::text ?0.1?
package require doctools::text

export serial configuration

Description

This package implements the doctools table of contents export plugin -for the generation of plain text markup.

This is an internal package of doctools, for use by the higher level -management packages handling tables of contents, especially doctools::toc::export, the export manager.

Using it from a regular interpreter is possible, however only with -contortions, and is not recommended. -The proper way to use this functionality is through the package -doctools::toc::export and the export manager objects it -provides.

API

The API provided by this package satisfies the specification of the -doctoc export plugin API version 2.

export serial configuration: This command takes the canonical serialization of a table of contents, -as specified in section ToC serialization format, and -contained in serial, the configuration, a dictionary, and -generates plain text markup encoding the table. -The created string is then returned as the result of the command.

Configuration

The text export plugin recognizes the following configuration -variables and changes its behaviour as they specify.

dictionary map

This standard configuration variable contains a dictionary mapping -from the (symbolic) document ids in reference entries to the actual -filenames and/or urls to be used in the output.

Document ids without a mapping are used unchanged.

Note that this plugin ignores the standard configuration -variables user, file, and format, and their values.

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

doctools, export, plain text, serialization, table of contents, toc

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_export_wiki.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_export_wiki.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_export_wiki.html +++ /dev/null @@ -1,287 +0,0 @@ - -

- -

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

Name

doctools::toc::export::wiki - wiki export plugin

Table Of Contents
Synopsis
Description
API
Wiki markup
Configuration
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::toc::export::wiki ?0.1?
package require doctools::text

export serial configuration

Description

This package implements the doctools table of contents export plugin -for the generation of wiki markup.

This is an internal package of doctools, for use by the higher level -management packages handling tables of contents, especially doctools::toc::export, the export manager.

Using it from a regular interpreter is possible, however only with -contortions, and is not recommended. -The proper way to use this functionality is through the package -doctools::toc::export and the export manager objects it -provides.

API

The API provided by this package satisfies the specification of the -doctoc export plugin API version 2.

export serial configuration: This command takes the canonical serialization of a table of contents, -as specified in section ToC serialization format, and -contained in serial, the configuration, a dictionary, and -generates wiki markup encoding the table. -The created string is then returned as the result of the command.

Wiki markup

The basic syntax of the wiki markup generated by this plugin are -described at http://wiki.tcl.tk/14.

The plugin goes beyond the classic markup to generate proper headers -and indenting.

Configuration

The wiki export plugin recognizes the following configuration -variables and changes its behaviour as they specify.

dictionary map

This standard configuration variable contains a dictionary mapping -from the (symbolic) document ids in reference entries to the actual -filenames and/or urls to be used in the output.

Document ids without a mapping are used unchanged.

Note that this plugin ignores the standard configuration -variables user, file and format, and their values.

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

doctools, export, serialization, table of contents, toc, wiki

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_import.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_import.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_import.html +++ /dev/null @@ -1,536 +0,0 @@ - -

- -

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

Name

doctools::toc::import - Importing keyword indices

Table Of Contents
Synopsis
Description
Concepts
API -
- Package commands
- Object command
- Object methods
-
Import plugin API v2 reference
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require doctools::toc::import ?0.2?
package require Tcl 8.4
package require doctools::config
package require doctools::toc::structure
package require snit
package require pluginmgr

::doctools::toc::import objectName
objectName method ?arg arg ...?
objectName destroy
objectName import text text ?format?
objectName import file path ?format?
objectName import object text object text ?format?
objectName import object file object path ?format?
objectName config names
objectName config get
objectName config set name ?value?
objectName config unset pattern...
objectName includes
objectName include add path
objectName include remove path
objectName include clear
IncludeFile currentfile path
import text configuration

Description

This package provides a class to manage the plugins for the import of -tables of contents from other formats, i.e. their conversion from, for -example doctoc, json, etc.

This is one of the three public pillars the management of tables of -contents resides on. The other two pillars are

Exporting tables of contents, and
Holding tables of contents

For information about the Concepts of tables of contents, -and their parts, see the same-named section. -For information about the data structure which is the major output of -the manager objects provided by this package see the section -ToC serialization format.

The plugin system of our class is based on the package -pluginmgr, and configured to look for plugins using

the environment variable DOCTOOLS_TOC_IMPORT_PLUGINS,
the environment variable DOCTOOLS_TOC_PLUGINS,
the environment variable DOCTOOLS_PLUGINS,
the path "~/.doctools/toc/import/plugin"
the path "~/.doctools/toc/plugin"
the path "~/.doctools/plugin"
the path "~/.doctools/toc/import/plugins"
the path "~/.doctools/toc/plugins"
the path "~/.doctools/plugins"
the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\IMPORT\PLUGINS"
the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\PLUGINS"
the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

The last three are used only when the package is run on a machine -using Windows(tm) operating system.

The whole system is delivered with two predefined import plugins, -namely

doctoc: See doctoc import plugin for details.
json: See json import plugin for details.

Concepts

A table of contents consists of a (possibly empty) list of -elements.
Each element in the list is identified by its label.
Each element is either a reference, or a division.
Each reference has an associated document, identified by a symbolic -id, and a textual description.
Each division may have an associated document, identified by a -symbolic id.
Each division consists consists of a (possibly empty) list of -elements, with each element following the rules as specified in -item 2 and above.

A few notes

The above rules span up a tree of elements, with references as the -leaf nodes, and divisions as the inner nodes, and each element -representing an entry in the whole table of contents.
The identifying labels of any element E are unique within their -division (or toc), and the full label of any element E is the list of -labels for all nodes on the unique path from the root of the tree to -E, including E.

API

Package commands

::doctools::toc::import objectName: This command creates a new import manager object with an associated -Tcl command whose name is objectName. This object command -is explained in full detail in the sections Object command -and Object methods. The object command will be created -under the current namespace if the objectName is not fully -qualified, and in the specified namespace otherwise.

Object command

All objects created by the ::doctools::toc::import command have -the following general form:

objectName method ?arg arg ...?: The method method and its arg'uments determine the -exact behavior of the command. -See section Object methods for the detailed -specifications.

Object methods

objectName destroy

This method destroys the object it is invoked for.

objectName import text text ?format?

This method takes the text and converts it from the specified -format to the canonical serialization of a table of contents using -the import plugin for the format. An error is thrown if no plugin -could be found for the format. -The serialization generated by the conversion process is returned as -the result of this method.

If no format is specified the method defaults to doctoc.

The specification of what a canonical serialization is can be -found in the section ToC serialization format.

The plugin has to conform to the interface specified in section -Import plugin API v2 reference.

objectName import file path ?format?

objectName import object text object text ?format?

This method is a convenient wrapper around the import text -method described by the previous item. -It expects that object is an object command supporting a -deserialize method expecting the canonical serialization of a -table of contents. -It imports the text using import text and then feeds the -resulting serialization into the object via deserialize. -This method returns the empty string as it result.

objectName import object file object path ?format?

This method behaves like import object text, except that it -reads the text to convert from the specified file instead of being -given it as argument.

objectName config names

This method returns a list containing the names of all configuration -variables currently known to the object.

objectName config get

This method returns a dictionary containing the names and values of -all configuration variables currently known to the object.

objectName config set name ?value?

This method sets the configuration variable name to the -specified value and returns the new value of the variable.

If no value is specified it simply returns the current value, without -changing it.

objectName config unset pattern...

This method unsets all configuration variables matching the specified -glob patterns. If no pattern is specified it will unset all -currently defined configuration variables.

objectName includes

objectName include add path

The method does nothing if the path is already known.

objectName include remove path

This methods removes the specified path from the list of paths -to use to search for include files when processing input. The result -of the command is the empty string.

The method does nothing if the path is not known.

objectName include clear

This method clears the list of paths to use to search for include -files when processing input. The result of the command is the empty -string.

Import plugin API v2 reference

Plugins are what this package uses to manage the support for any input -format beyond the ToC serialization format. Here we -specify the API the objects created by this package use to interact -with their plugins.

A plugin for this package has to follow the rules listed below:

A plugin is a package.
The name of a plugin package has the form - doctools::toc::import::FOO, - where FOO is the name of the format the plugin will - generate output for. This name is also the argument to provide - to the various import methods of import manager - objects to get a string encoding a table of contents in that - format.
The plugin can expect that the package - doctools::toc::export::plugin is present, as - indicator that it was invoked from a genuine plugin manager.
The plugin can expect that a command named IncludeFile is - present, with the signature
-
-
IncludeFile currentfile path
-
This command has to be invoked by the plugin when it has to process an -included file, if the format has the concept of such. An example of -such a format would be doctoc.
-
The plugin has to supply the following arguments
-
-
string currentfile
-
The path of the file it is currently processing. This may be the empty -string if no such is known.
-
string path
-
The path of the include file as specified in the include directive -being processed.
-
-
The result of the command will be a 5-element list containing
-
1. A boolean flag indicating the success (True) or failure - (False) of the operation.
2. In case of success the contents of the included file, and the - empty string otherwise.
3. The resolved, i.e. absolute path of the included file, if - possible, or the unchanged path argument. This is for - display in an error message, or as the currentfile - argument of another call to IncludeFile should this file - contain more files.
4. In case of success an empty string, and for failure a code - indicating the reason for it, one of
  -
  -
  notfound
  -
  The specified file could not be found.
  -
  notread
  -
  The specified file was found, but not be read into memory.
  -
  -
5. An empty string in case of success of a notfound - failure, and an additional error message describing the reason - for a notread error in more detail.
-
-
A plugin has to provide one command, with the signature shown - below.
-
-
import text configuration
-
Whenever an import manager of doctools::toc has to parse -input for a table of contents it will invoke this command.
-
-
string text
-
This argument will contain the text encoding the table of contents per -the format the plugin is for.
-
dictionary configuration
-
This argument will contain the current configuration to apply to the -parsing, as a dictionary mapping from variable names to values.
-
The following configuration variables have a predefined meaning all -plugins have to obey, although they can ignore this information at -their discretion. Any other other configuration variables recognized -by a plugin will be described in the manpage for that plugin.
-
-
user
-
This variable is expected to contain the name of the user - owning the process invoking the plugin.
-
format
-
This variable is expected to contain the name of the - format whose plugin is invoked.
-
-
-
-
A single usage cycle of a plugin consists of the invokations of - the command import. This call has to leave the plugin in - a state where another usage cycle can be run without problems.

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

conversion, doctoc, documentation, import, json, manpage, markup, parsing, plugin, reference, table, table of contents, url

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_import_json.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_import_json.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_import_json.html +++ /dev/null @@ -1,337 +0,0 @@ - -

- -

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

Name

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

Table Of Contents
Synopsis
Description
API
JSON notation of tables of contents
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require doctools::toc::import::json ?0.1?
package require doctools::toc::structure
package require json

import string configuration

Description

This package implements the doctools table of contents import plugin -for the parsing of JSON markup.

This is an internal package of doctools, for use by the higher level -management packages handling tables of contents, especially doctools::toc::import, the import manager.

Using it from a regular interpreter is possible, however only with -contortions, and is not recommended. -The proper way to use this functionality is through the package -doctools::toc::import and the import manager objects it -provides.

API

The API provided by this package satisfies the specification of the -doctoc import plugin API version 2.

import string configuration: This command takes the string and parses it as JSON -markup encoding a table of contents, in the context of the specified -configuration (a dictionary). The result of the command is the -canonical serialization of that table of contents, in the form -specified in section ToC serialization format.

JSON notation of tables of contents

-doctools::toc {
-    items {
-        {reference {
-	    desc {DocTools - Tables of Contents}
-	     id introduction.man
-	     label doctools::toc::introduction
-	}}
-	{division {
-	     id processing.man
-	     items {
-	         {reference {
-		     desc {doctoc serialization utilities}
-		     id structure.man
-		     label doctools::toc::structure
-		 }}
-		 {reference {
-		     desc {Parsing text in doctoc format}
-		     id parse.man
-		     label doctools::toc::parse
-		 }}
-	     }
-             label Processing
-        }}
-    }
-    label {Table of Contents} 
-    title TOC
-}
-

is equivalent to the JSON string

-{
-    "doctools::toc" : {
-        "items" : [{
-            "reference" : {
-                "desc"  : "DocTools - Tables of Contents",
-                "id"    : "introduction.man",
-                "label" : "doctools::toc::introduction"
-            }
-        },{
-            "division" : {
-                "id"    : "processing.man",
-                "items" : [{
-                    "reference" : {
-                        "desc"  : "doctoc serialization utilities",
-                        "id"    : "structure.man",
-                        "label" : "doctools::toc::structure"
-                    }
-                },{
-                    "reference" : {
-                        "desc"  : "Parsing text in doctoc format",
-                        "id"    : "parse.man",
-                        "label" : "doctools::toc::parse"
-                    }
-                }],
-                "label" : "Processing"
-            }
-        }],
-        "label" : "Table of Contents",
-        "title" : "TOC"
-    }
-}
-

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

JSON, deserialization, doctools, import, table of contents, toc

Category

Text formatter plugin

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_introduction.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_introduction.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_introduction.html +++ /dev/null @@ -1,257 +0,0 @@ - -

- -

doctools2toc_introduction(n) 2.0 tcllib "Documentation tools"

Name

doctools2toc_introduction - DocTools - Tables of Contents

Table Of Contents
Description
Related formats
Package Overview
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Description

These are

A tcl based language for the semantic markup of a table of contents. -Markup is represented by Tcl commands. -Beginners should start with the -doctoc language introduction. -The formal specification is split over two documents, one dealing with -the doctoc language syntax, the other a -doctoc language command reference.
A set of packages for the programmatic manipulation of tables of -contents in memory, and their conversion between various formats, -reading and writing. The aforementioned markup language is one of the -formats which can be both read from and written to.
The system for the conversion of tables of contents is based on a -plugin mechanism, for this we have two APIs describing the interface -between the packages above and the import/export plugins.

Which of the more detailed documents are relevant to the reader of -this introduction depends on their role in the documentation process.

A writer of documentation has to understand the markup language -itself. A beginner to doctoc should read the more informally written -doctoc language introduction first. Having digested this -the formal doctoc language syntax specification should -become understandable. A writer experienced with doctoc may only -need the doctoc language command reference from time to -time to refresh her memory.
-
While a document is written the dtp application can be used -to validate it, and after completion it also performs the conversion -into the chosen system of visual markup, be it *roff, HTML, plain -text, wiki, etc. The simpler dtplite application makes -internal use of doctoc when handling directories of documentation, -automatically generating a proper table of contents for them.
A processor of documentation written in the doctoc -markup language has to know which tools are available for use.
-
The main tool is the aforementioned dtp application provided -by Tcllib. The simpler dtplite does not expose doctoc to the -user. At the bottom level, common to both applications, however we -find the three packages providing the basic facilities to handle -tables of contents, i.e. import from textual formats, programmatic -manipulation in memory, and export to textual formats. These are
-
-
doctoools::toc
-
Programmatic manipulation of tables of contents in memory.
-
doctoools::toc::import
-
Import of tables of contents from various textual formats. The set of -supported formats is extensible through plugin packages.
-
doctoools::toc::export
-
Export of tables of contents to various textual formats. The set of -supported formats is extensible through plugin packages.
-
-
See also section Package Overview for an overview of the -dependencies between these and other, supporting packages.
At last, but not least, plugin writers have to understand the -interaction between the import and export packages and their plugins. -These APIs are described in the documentation for the two relevant -packages, i.e.
-
- doctoools::toc::import
- doctoools::toc::export
-

Related formats

The doctoc format does not stand alone, it has two companion formats. -These are called docidx and doctools, and they are -intended for the markup of keyword indices, and of general -documentation, respectively. -They are described in their own sets of documents, starting at -the DocTools - Keyword Indices and -the DocTools - General, respectively.

Package Overview

-                                    ~~~~~~~~~~~ doctools::toc ~~~~~~~~~~~
-                                   ~~                   |               ~~
-                doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import
-                        |                               |                       |
-        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
-        |               |                         |     |    |                  |               |                       |               |
-doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
-                        |                         |     |    |                  |
-                doctools::toc::export::<*>        |     |    |          doctools::toc::import::<*>
-                        doctoc                    |     |    |                  doctoc, json
-                        json                      |     |    |                  |           \\
-                        html                      |     |    |          doctools::toc::parse \\
-                        nroff                     |     |    |                  |             \\
-                        wiki                      |     |    |  +---------------+              json
-                        text                      |     |    |  |               |
-                                                doctools::toc::structure        |
-                                                                                |
-                                                                        +-------+---------------+
-                                                                        |                       |
-          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat        
-                |                                                                               |
-          doctools::text  doctools::nroff::man_macros                                           =
-                                                                                                |
-                                                                                        doctools::msgcat::toc::<*>
-                                                                                                c, en, de, fr
-                                                                                                (fr == en for now)
-        ~~      Interoperable objects, without actual package dependencies
-        --      Package dependency, higher requires lower package
-        =       Dynamic dependency through plugin system
-        <*>     Multiple packages following the given form of naming.
-

Bugs, Ideas, Feedback

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

Keywords

contents, conversion, formatting, markup, parsing, plugin, semantic markup, table of contents

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_c.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_c.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_c.html +++ /dev/null @@ -1,171 +0,0 @@ - -

- -

doctools::msgcat::toc::c(n) 0.1 tcllib "Documentation tools"

Name

doctools::msgcat::toc::c - Message catalog for the doctoc parser (C)

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require msgcat
package require doctools::msgcat::toc::c ?0.1?

Description

The package doctools::msgcat::toc::c is a -support module providing the C language message catalog -for the doctoc parser in the doctools system version 2. As such it is -an internal package a regular user (developer) should not be in direct -contact with.

If you are such please go the documentation of either

doctools::doc,
doctools::toc, or
doctools::idx

API

This package has no exported API.

Bugs, Ideas, Feedback

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

Keywords

C, catalog package, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_de.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_de.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_de.html +++ /dev/null @@ -1,171 +0,0 @@ - -

- -

doctools::msgcat::toc::de(n) 0.1 tcllib "Documentation tools"

Name

doctools::msgcat::toc::de - Message catalog for the doctoc parser (DE)

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require msgcat
package require doctools::msgcat::toc::de ?0.1?

Description

The package doctools::msgcat::toc::de is a -support module providing the DE (german) language message catalog -for the doctoc parser in the doctools system version 2. As such it is -an internal package a regular user (developer) should not be in direct -contact with.

If you are such please go the documentation of either

doctools::doc,
doctools::toc, or
doctools::idx

API

This package has no exported API.

Bugs, Ideas, Feedback

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

Keywords

DE, catalog package, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_en.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_en.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_en.html +++ /dev/null @@ -1,171 +0,0 @@ - -

- -

doctools::msgcat::toc::en(n) 0.1 tcllib "Documentation tools"

Name

doctools::msgcat::toc::en - Message catalog for the doctoc parser (EN)

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require msgcat
package require doctools::msgcat::toc::en ?0.1?

Description

The package doctools::msgcat::toc::en is a -support module providing the EN (english) language message catalog -for the doctoc parser in the doctools system version 2. As such it is -an internal package a regular user (developer) should not be in direct -contact with.

If you are such please go the documentation of either

doctools::doc,
doctools::toc, or
doctools::idx

API

This package has no exported API.

Bugs, Ideas, Feedback

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

Keywords

EN, catalog package, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_fr.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_fr.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_fr.html +++ /dev/null @@ -1,171 +0,0 @@ - -

- -

doctools::msgcat::toc::fr(n) 0.1 tcllib "Documentation tools"

Name

doctools::msgcat::toc::fr - Message catalog for the doctoc parser (FR)

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require msgcat
package require doctools::msgcat::toc::fr ?0.1?

Description

The package doctools::msgcat::toc::fr is a -support module providing the FR (french) language message catalog -for the doctoc parser in the doctools system version 2. As such it is -an internal package a regular user (developer) should not be in direct -contact with.

If you are such please go the documentation of either

doctools::doc,
doctools::toc, or
doctools::idx

API

This package has no exported API.

Bugs, Ideas, Feedback

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

Keywords

FR, catalog package, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_parse.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_parse.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_parse.html +++ /dev/null @@ -1,371 +0,0 @@ - -

- -

doctools::toc::parse(n) 1 tcllib "Documentation tools"

Name

doctools::toc::parse - Parsing text in doctoc format

Table Of Contents
Synopsis
Description
API
Parse errors
[doctoc] notation of tables of contents
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require doctools::toc::parse ?0.1?
package require Tcl 8.4
package require doctools::toc::structure
package require doctools::msgcat
package require doctools::tcl::parse
package require fileutil
package require logger
package require snit
package require struct::list
package require struct::stack

::doctools::toc::parse text text
::doctools::toc::parse file path
::doctools::toc::parse includes
::doctools::toc::parse include add path
::doctools::toc::parse include remove path
::doctools::toc::parse include clear
::doctools::toc::parse vars
::doctools::toc::parse var set name value
::doctools::toc::parse var unset name
::doctools::toc::parse var clear ?pattern?

Description

This package provides commands to parse text written in the -doctoc markup language and convert it into the canonical -serialization of the table of contents encoded in the text. -See the section ToC serialization format for specification -of their format.

This is an internal package of doctools, for use by the higher level -packages handling doctoc documents.

API

::doctools::toc::parse text text

The command takes the string contained in text and parses it -under the assumption that it contains a document written using the -doctoc markup language. An error is thrown if this assumption -is found to be false. The format of these errors is described in -section Parse errors.

When successful the command returns the canonical serialization of the -table of contents which was encoded in the text. -See the section ToC serialization format for specification -of that format.

::doctools::toc::parse file path

The same as text, except that the text to parse is read from -the file specified by path.

::doctools::toc::parse includes

This method returns the current list of search paths used when looking -for include files.

::doctools::toc::parse include add path

::doctools::toc::parse include remove path

::doctools::toc::parse include clear

This method clears the list of search paths for include files.

::doctools::toc::parse vars

This method returns a dictionary containing the current set of -predefined variables known to the vset markup command during -processing.

::doctools::toc::parse var set name value

::doctools::toc::parse var unset name

This method removes the variable name from the set of predefined -variables known to the vset markup command during -processing. The method returns the empty string as its result.

::doctools::toc::parse var clear ?pattern?

The pattern matching is done with string match, and the -default pattern used when none is specified, is *.

Parse errors

The format of the parse error messages thrown when encountering -violations of the doctoc markup syntax is human readable and -not intended for processing by machines. As such it is not documented.

However, the errorCode attached to the message is -machine-readable and has the following format:

The error code will be a list, each element describing a single error -found in the input. The list has at least one element, possibly more.
Each error element will be a list containing six strings describing an -error in detail. The strings will be
-
1. The path of the file the error occurred in. This may be empty.
2. The range of the token the error was found at. This range is a -two-element list containing the offset of the first and last character -in the range, counted from the beginning of the input (file). Offsets -are counted from zero.
3. The line the first character after the error is on. -Lines are counted from one.
4. The column the first character after the error is at. -Columns are counted from zero.
5. The message code of the error. This value can be used as argument to -msgcat::mc to obtain a localized error message, assuming that -the application had a suitable call of doctools::msgcat::init to -initialize the necessary message catalogs (See package -doctools::msgcat).
6. A list of details for the error, like the markup command involved. In -the case of message code doctoc/include/syntax this value is -the set of errors found in the included file, using the format -described here.
-

[doctoc] notation of tables of contents

The doctoc format for tables of contents, also called the -doctoc markup language, is too large to be covered in single -section. -The interested reader should start with the document

doctoc language introduction

and then proceed from there to the formal specifications, i.e. the -documents

doctoc language syntax and
doctoc language command reference.

to get a thorough understanding of the language.

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

doctoc, doctools, lexer, parser

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/doctools2toc/toc_structure.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_structure.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_structure.html +++ /dev/null @@ -1,324 +0,0 @@ - -

- -

doctools::toc::structure(n) 0.1 tcllib "Documentation tools"

Name

doctools::toc::structure - Doctoc serialization utilities

Table Of Contents
Synopsis
Description
API
ToC serialization format
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require doctools::toc::structure ?0.1?
package require Tcl 8.4
package require logger
package require snit

::doctools::toc::structure verify serial ?canonvar?
::doctools::toc::structure verify-as-canonical serial
::doctools::toc::structure canonicalize serial
::doctools::toc::structure print serial
::doctools::toc::structure merge seriala serialb

Description

This package provides commands to work with the serializations of -tables of contents as managed by the doctools system v2, and specified -in section ToC serialization format.

This is an internal package of doctools, for use by the higher level -packages handling tables of contents and their conversion into and out -of various other formats, like documents written using doctoc -markup.

API

::doctools::toc::structure verify serial ?canonvar?

This command verifies that the content of serial is a valid -regular serialization of a table of contents and will throw an -error if that is not the case. The result of the command is the empty -string.

For the specification of regular and canonical serializations see the -section ToC serialization format.

::doctools::toc::structure verify-as-canonical serial

This command verifies that the content of serial is a valid -canonical serialization of a table of contents and will throw -an error if that is not the case. The result of the command is the -empty string.

For the specification of canonical serializations see the section -ToC serialization format.

::doctools::toc::structure canonicalize serial

This command assumes that the content of serial is a valid -regular serialization of a table of contents and will throw an -error if that is not the case.

It will then convert the input into the canonical serialization -of the contained table of contents and return it as its result. If the -input is already canonical it will be returned unchanged.

For the specification of regular and canonical serializations see the -section ToC serialization format.

::doctools::toc::structure print serial

This command assumes that the argument serial contains a valid -regular serialization of a table of contents and returns a string -containing that table in a human readable form.

The exact format of this form is not specified and cannot be relied on -for parsing or other machine-based activities.

For the specification of regular serializations see the section -ToC serialization format.

::doctools::toc::structure merge seriala serialb

This command accepts the regular serializations of two tables of -contents and uses them to create their union. The result of the -command is the canonical serialization of this unified table of -contents.

Title and label of the resulting table are taken from the table -contained in serialb.

The whole table and its divisions are merged recursively in the same -manner:

All reference elements which occur in both divisions (identified by -their label) are unified with document id's and descriptions taken -from the second table.
All division elements which occur in both divisions (identified by -their label) are unified with the optional document id taken from the -second table, if any, or from the first if none is in the second. The -elements in the division are merged recursively using the same -algorithm as described in this list.
Type conflicts between elements, i.e. finding two elements with the -same label but different types result in a merge error.
All elements found in the second division but not in the first are -added to the end of the list of elements in the merge result.

For the specification of regular and canonical serializations see the -section ToC serialization format.

ToC serialization format

Here we specify the format used by the doctools v2 packages to -serialize tables of contents as immutable values for transport, -comparison, etc.

We distinguish between regular and canonical -serializations. -While a table of contents may have more than one regular serialization -only exactly one of them will be canonical.

regular serialization

The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, doctools::toc, and its -value. This value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the -title of the table of contents, a label, and its elements. The -relevant keys and their values are
-
-
title
-
The value is a string containing the title of the table of contents.
-
label
-
The value is a string containing a label for the table of contents.
-
items
-
The value is a Tcl list holding the elements of the table, in the -order they are to be shown.
-
Each element is a Tcl list holding the type of the item, and its -description, in this order. An alternative description would be that -it is a Tcl dictionary holding a single key, the item type, mapped to -the item description.
-
The two legal item types and their descriptions are
-
-
reference
-
This item describes a single entry in the table of contents, -referencing a single document. -To this end its value is a Tcl dictionary containing an id for the -referenced document, a label, and a longer textual description which -can be associated with the entry. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the entry.
-
label
-
The value is a string containing a label for this entry. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
desc
-
The value is a string containing a longer description for this entry.
-
-
division
-
This item describes a group of entries in the table of contents, -inducing a hierarchy of entries. -To this end its value is a Tcl dictionary containing a label for the -group, an optional id to a document for the whole group, and the list -of entries in the group. -The relevant keys and their values are
-
-
id
-
The value is a string containing the id of the document associated -with the whole group. This key is optional.
-
label
-
The value is a string containing a label for the group. This string -also identifies the entry, and no two entries (references and -divisions) in the containing list are allowed to have the same label.
-
items
-
The value is a Tcl list holding the elements of the group, in the -order they are to be shown. -This list has the same structure as the value for the keyword -items used to describe the whole table of contents, see -above. This closes the recusrive definition of the structure, with -divisions holding the same type of elements as the whole table of -contents, including other divisions.
-
-
-
-

canonical serialization

The keys found in all the nested Tcl dictionaries are sorted in -ascending dictionary order, as generated by Tcl's builtin command -lsort -increasing -dict.

Bugs, Ideas, Feedback

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

Keywords

deserialization, doctoc, doctools, serialization

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/dtplite/pkg_dtplite.html Index: embedded/www/tcllib/files/modules/dtplite/pkg_dtplite.html ================================================================== --- embedded/www/tcllib/files/modules/dtplite/pkg_dtplite.html +++ /dev/null @@ -1,436 +0,0 @@ - -

- -

dtplite(n) 1.3.1 tcllib "Documentation toolbox"

Name

dtplite - Lightweight DocTools Markup Processor

Table Of Contents
Synopsis
Description -
- USE CASES
- COMMAND LINE
- OPTIONS
- FORMATS
- DIRECTORY STRUCTURES
-
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require dtplite ?1.3.1?

dtplite -o output ?options? format inputfile
dtplite validate inputfile
dtplite -o output ?options? format inputdirectory
dtplite -merge -o output ?options? format inputdirectory

Description

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

USE CASES

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

Validation of a single document, i.e. checking that it was written in -valid doctools format. This mode can also be used to get a preliminary -version of the formatted output for a single document, for display in -a browser, nroff, etc., allowing proofreading of the formatting.
Generation of the formatted documentation for a single package, -i.e. all the manpages, plus a table of contents and an index of -keywords.
An extension of the previous mode of operation, a method for the easy -generation of one documentation tree for several packages, and -especially of a unified table of contents and keyword index.

COMMAND LINE

dtplite -o output ?options? format inputfile

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

path output (in)

(path|handle) format (in)

path inputfile (in)

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

dtplite validate inputfile

dtplite -o output ?options? format inputdirectory

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

dtplite -merge -o output ?options? format inputdirectory

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

OPTIONS

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

-exclude string

-ext string

When used multiple times only the last definition is relevant.

-header file

When used multiple times only the last definition is relevant.

-footer file

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

When used multiple times only the last definition is relevant.

-style file

When used multiple times only the last definition is relevant.

-toc path|text

This option specifies a doctoc file (or text) to use for the table of contents -instead of generating our own.

When used multiple times only the last definition is relevant.

-pre+toc label path|text

-post+toc label path|text

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

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

-nav label url

-prenav label url

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

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

-postnav label url

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

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

FORMATS

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

nroff: The processor generates *roff output, the standard format for unix -manpages.
html: The processor generates HTML output, for usage in and display by web -browsers. This engine is currently the only one providing the various -engine parameters required for the additional customaization of the -output.
tmml: The processor generates TMML output, the Tcl Manpage Markup Language, -a derivative of XML.
latex: The processor generates LaTeX output.
wiki: The processor generates Wiki markup as understood by wikit.
list: The processor extracts the information provided by manpage_begin. -This format is used internally to extract the meta data from which -both table of contents and keyword index are derived from.
null: The processor does not generate any output. This is equivalent to -validate.

DIRECTORY STRUCTURES

[2]

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

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

-    inputdirectory/path/to/FOO
-

[3]

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

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

Bugs, Ideas, Feedback

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

Keywords

HTML, TMML, conversion, docidx, doctoc, doctools, manpage, markup, nroff

Category

Documentation tools

Copyright

DELETED embedded/www/tcllib/files/modules/fileutil/fileutil.html Index: embedded/www/tcllib/files/modules/fileutil/fileutil.html ================================================================== --- embedded/www/tcllib/files/modules/fileutil/fileutil.html +++ /dev/null @@ -1,537 +0,0 @@ - -

- -

fileutil(n) 1.16 tcllib "file utilities"

Name

fileutil - Procedures implementing some file utilities

Table Of Contents
Synopsis
Description
Warnings and Incompatibilities
Bugs, Ideas, Feedback
Keywords
Category

Synopsis

package require Tcl 8
package require fileutil ?1.16?

::fileutil::lexnormalize path
::fileutil::fullnormalize path
::fileutil::test path codes ?msgvar? ?label?
::fileutil::cat (?options? file)...
::fileutil::writeFile ?options? file data
::fileutil::appendToFile ?options? file data
::fileutil::insertIntoFile ?options? file at data
::fileutil::removeFromFile ?options? file at n
::fileutil::replaceInFile ?options? file at n data
::fileutil::updateInPlace ?options? file cmd
::fileutil::fileType filename
::fileutil::find ?basedir ?filtercmd??
::fileutil::findByPattern basedir ?-regexp|-glob? ?--? patterns
::fileutil::foreachLine var filename cmd
::fileutil::grep pattern ?files?
::fileutil::install ?-m mode? source destination
::fileutil::stripN path n
::fileutil::stripPwd path
::fileutil::stripPath prefix path
::fileutil::jail jail path
::fileutil::touch ?-a? ?-c? ?-m? ?-r ref_file? ?-t time? filename ?...?
::fileutil::tempdir
::fileutil::tempdir path
::fileutil::tempdirReset
::fileutil::tempfile ?prefix?
::fileutil::maketempdir ?-prefix str? ?-suffix str? ?-dir str?
::fileutil::relative base dst
::fileutil::relativeUrl base dst

Description

This package provides implementations of standard unix utilities.

::fileutil::lexnormalize path

This command performs purely lexical normalization on the path and returns -the changed path as its result. Symbolic links in the path are not resolved.

Examples:

-    fileutil::lexnormalize /foo/./bar
-    => /foo/bar
-    fileutil::lexnormalize /foo/../bar
-    => /bar
-

::fileutil::fullnormalize path

This command resolves all symbolic links in the path and returns -the changed path as its result. -In contrast to the builtin file normalize this command -resolves a symbolic link in the last element of the path as well.

::fileutil::test path codes ?msgvar? ?label?

A command for the testing of several properties of a path. The -properties to test for are specified in codes, either as a list -of keywords describing the properties, or as a string where each -letter is a shorthand for a property to test. The recognized keywords, -shorthands, and associated properties are shown in the list below. The -tests are executed in the order given to the command.

The result of the command is a boolean value. It will be true if and -only if the path passes all the specified tests. -In the case of the path not passing one or more test the first -failing test will leave a message in the variable referenced by -msgvar, if such is specified. The message will be prefixed with -label, if it is specified. -Note that the variabled referenced by msgvar is not touched at -all if all the tests pass.

read: file readable
write: file writable
exists: file exists
exec: file executable
file: file isfile
dir: file isdirectory

::fileutil::cat (?options? file)...

A tcl implementation of the UNIX cat command. Returns the -contents of the specified file(s). The arguments are files to read, -with interspersed options configuring the process. If there are -problems reading any of the files, an error will occur, and no data -will be returned.

The options accepted are -encoding, -translation, --eofchar, and --. With the exception of the last all -options take a single value as argument, as specified by the tcl -builtin command fconfigure. The -- has to be used to -terminate option processing before a file if that file's name begins -with a dash.

Each file can have its own set of options coming before it, and for -anything not specified directly the defaults are inherited from the -options of the previous file. The first file inherits the system -default for unspecified options.

::fileutil::writeFile ?options? file data

The command replaces the current contents of the specified file -with data, with the process configured by the options. The -command accepts the same options as ::fileutil::cat. The -specification of a non-existent file is legal and causes the command -to create the file (and all required but missing directories).

::fileutil::appendToFile ?options? file data

This command is like ::fileutil::writeFile, except that the -previous contents of file are not replaced, but appended to. The -command accepts the same options as ::fileutil::cat

::fileutil::insertIntoFile ?options? file at data

This comment is similar to ::fileutil::appendToFile, except that -the new data is not appended at the end, but inserted at a specified -location within the file. In further contrast this command has to be -given the path to an existing file. It will not create a missing file, -but throw an error instead.

The specified location at has to be an integer number in the -range 0 ... [file size file]. 0 will cause -insertion of the new data before the first character of the existing -content, whereas [file size file] causes insertion after -the last character of the existing content, i.e. appending.

The command accepts the same options as ::fileutil::cat.

::fileutil::removeFromFile ?options? file at n

This command is the complement to ::fileutil::insertIntoFile, removing n characters from the file, starting at location at. -The specified location at has to be an integer number in the -range 0 ... [file size file] - n. 0 -will cause the removal of the new data to start with the first -character of the existing content, -whereas [file size file] - n causes the removal of -the tail of the existing content, i.e. the truncation of the file.

The command accepts the same options as ::fileutil::cat.

::fileutil::replaceInFile ?options? file at n data

This command is a combination of ::fileutil::removeFromFile and -::fileutil::insertIntoFile. It first removes the part of the -contents specified by the arguments at and n, and then -inserts data at the given location, effectively replacing the -removed by content with data. -All constraints imposed on at and n by -::fileutil::removeFromFile and ::fileutil::insertIntoFile -are obeyed.

The command accepts the same options as ::fileutil::cat.

::fileutil::updateInPlace ?options? file cmd

This command can be seen as the generic core functionality of -::fileutil::replaceInFile. -It first reads the contents of the specified file, then runs the -command prefix cmd with that data appended to it, and at last -writes the result of that invokation back as the new contents of the -file.

If the executed command throws an error the file is not changed.

The command accepts the same options as ::fileutil::cat.

::fileutil::fileType filename

An implementation of the UNIX file command, which uses -various heuristics to guess the type of a file. Returns a list -specifying as much type information as can be determined about the -file, from most general (eg, "binary" or "text") to most specific (eg, -"gif"). For example, the return value for a GIF file would be "binary -graphic gif". The command will detect the following types of files: -directory, empty, binary, text, script (with interpreter), executable -elf, executable dos, executable ne, executable pe, graphic gif, graphic -jpeg, graphic png, graphic tiff, graphic bitmap, html, xml (with doctype -if available), message pgp, binary pdf, text ps, text eps, binary -gravity_wave_data_frame, compressed bzip, compressed gzip, compressed -zip, compressed tar, audio wave, audio mpeg, and link. It further -detects doctools, doctoc, and docidx documentation files, and -tklib diagrams.

::fileutil::find ?basedir ?filtercmd??

An implementation of the unix command find. Adapted from the -Tcler's Wiki. Takes at most two arguments, the path to the directory -to start searching from and a command to use to evaluate interest in -each file. The path defaults to ".", i.e. the current -directory. The command defaults to the empty string, which means that -all files are of interest. The command takes care not to -lose itself in infinite loops upon encountering circular link -structures. The result of the command is a list containing the paths -to the interesting files.

The filtercmd, if specified, is interpreted as a command prefix -and one argument is added to it, the name of the file or directory -find is currently looking at. Note that this name is not fully -qualified. It has to be joined it with the result of pwd to get -an absolute filename.

The result of filtercmd is a boolean value that indicates if the -current file should be included in the list of interesting files.

Example:

-    # find .tcl files
-    package require fileutil
-    proc is_tcl {name} {return [string match *.tcl $name]}
-    set tcl_files [fileutil::find . is_tcl]
-

::fileutil::findByPattern basedir ?-regexp|-glob? ?--? patterns

This command is based upon the TclX command -recursive_glob, except that it doesn't allow recursion over more -than one directory at a time. It uses ::fileutil::find -internally and is thus able to and does follow symbolic links, -something the TclX command does not do. First argument is -the directory to start the search in, second argument is a list of -patterns. The command returns a list of all files reachable -through basedir whose names match at least one of the -patterns. The options before the pattern-list determine the style of -matching, either regexp or glob. glob-style matching is the default if -no options are given. Usage of the option -- stops option -processing. This allows the use of a leading '-' in the patterns.

::fileutil::foreachLine var filename cmd

The command reads the file filename and executes the script -cmd for every line in the file. During the execution of the -script the variable var is set to the contents of the current -line. The return value of this command is the result of the last -invocation of the script cmd or the empty string if the file was -empty.

::fileutil::grep pattern ?files?

Implementation of grep. Adapted from the Tcler's Wiki. The -first argument defines the pattern to search for. This is -followed by a list of files to search through. The list is -optional and stdin will be used if it is missing. The result -of the procedures is a list containing the matches. Each match is a -single element of the list and contains filename, number and contents -of the matching line, separated by a colons.

::fileutil::install ?-m mode? source destination

The install command is similar in functionality to the install -command found on many unix systems, or the shell script -distributed with many source distributions (unix/install-sh in the Tcl -sources, for example). It copies source, which can be either a -file or directory to destination, which should be a directory, -unless source is also a single file. The ?-m? option lets -the user specify a unix-style mode (either octal or symbolic - see -file attributes.

::fileutil::stripN path n

Removes the first n elements from the specified path and -returns the modified path. If n is greater than the number of -components in path an empty string is returned. The number of -components in a given path may be determined by performing -llength on the list returned by file split.

::fileutil::stripPwd path

If, and only if the path is inside of the directory returned by -[pwd] (or the current working directory itself) it is made -relative to that directory. In other words, the current working -directory is stripped from the path. The possibly modified path -is returned as the result of the command. If the current working -directory itself was specified for path the result is the string -".".

::fileutil::stripPath prefix path

If, and only of the path is inside of the directory -"prefix" (or the prefix directory itself) it is made relative to -that directory. In other words, the prefix directory is stripped from -the path. The possibly modified path is returned as the result -of the command. -If the prefix directory itself was specified for path the result -is the string ".".

::fileutil::jail jail path

This command ensures that the path is not escaping the directory -jail. It always returns an absolute path derived from path -which is within jail.

If path is an absolute path and already within jail it is -returned unmodified.

An absolute path outside of jail is stripped of its root element -and then put into the jail by prefixing it with it. The same -happens if path is relative, except that nothing is stripped of -it. Before adding the jail prefix the path is lexically -normalized to prevent the caller from using .. segments in -path to escape the jail.

::fileutil::touch ?-a? ?-c? ?-m? ?-r ref_file? ?-t time? filename ?...?

Implementation of touch. Alter the atime and mtime of the -specified files. If -c, do not create files if they do not -already exist. If -r, use the atime and mtime from -ref_file. If -t, use the integer clock value -time. It is illegal to specify both -r and --t. If -a, only change the atime. If -m, -only change the mtime.

This command is not available for Tcl versions less than 8.3.

::fileutil::tempdir

The command returns the path of a directory where the caller can -place temporary files, such as "/tmp" on Unix systems. The -algorithm we use to find the correct directory is as follows:

The directory set by an invokation of ::fileutil::tempdir with -an argument. If this is present it is tried exclusively and none of -the following item are tried.
The directory named in the TMPDIR environment variable.
The directory named in the TEMP environment variable.
The directory named in the TMP environment variable.
A platform specific location:
-
-
Windows
-
"C:\TEMP", "C:\TMP", "\TEMP", -and "\TMP" are tried in that order.
-
(classic) Macintosh
-
The TRASH_FOLDER environment variable is used. This is most likely -not correct.
-
Unix
-
The directories "/tmp", "/var/tmp", and "/usr/tmp" are -tried in that order.
-
-

The algorithm utilized is mainly that used in the Python standard -library. The exception is the first item, the ability to have the -search overridden by a user-specified directory.

::fileutil::tempdir path

In this mode the command sets the path as the first and only -directory to try as a temp. directory. See the previous item for the -use of the set directory. The command returns the empty string.

::fileutil::tempdirReset

Invoking this command clears the information set by the -last call of [::fileutil::tempdir path]. -See the last item too.

::fileutil::tempfile ?prefix?

The command generates a temporary file name suitable for writing to, -and the associated file. The file name will be unique, and the file -will be writable and contained in the appropriate system specific temp -directory. The name of the file will be returned as the result of the -command.

The code was taken from http://wiki.tcl.tk/772, attributed to -Igor Volobouev and anon.

::fileutil::maketempdir ?-prefix str? ?-suffix str? ?-dir str?

The command generates a temporary directory suitable for writing to. -The directory name will be unique, and the directory will be writable -and contained in the appropriate system specific temp directory. The -name of the directory will be returned as the result of the command.

The three options can used to tweak the behaviour of the command:

-prefix str: The initial, fixed part of the directory name. Defaults to tmp if not specified.
-suffix str: The fixed tail of the directory. Defaults to the empty string if not specified.
-dir str: The directory to place the new directory into. Defaults to the result of fileutil::tempdir if not specified.

The initial code for this was supplied by Miguel Martinez Lopez.

::fileutil::relative base dst

This command takes two directory paths, both either absolute or relative -and computes the path of dst relative to base. This relative -path is returned as the result of the command. As implied in the previous -sentence, the command is not able to compute this relationship between the -arguments if one of the paths is absolute and the other relative.

Note: The processing done by this command is purely lexical. -Symbolic links are not taken into account.

::fileutil::relativeUrl base dst

This command takes two file paths, both either absolute or relative -and computes the path of dst relative to base, as seen -from inside of the base. This is the algorithm how a browser -resolves a relative link found in the currently shown file.

The computed relative path is returned as the result of the command. -As implied in the previous sentence, the command is not able to compute -this relationship between the arguments if one of the paths is absolute -and the other relative.

Note: The processing done by this command is purely lexical. -Symbolic links are not taken into account.

Warnings and Incompatibilities

1.14.9

In this version fileutil::find's broken system for handling -symlinks was replaced with one working correctly and properly -enumerating all the legal non-cyclic paths under a base directory.

While correct this means that certain pathological directory -hierarchies with cross-linked sym-links will now take about O(n**2) -time to enumerate whereas the original broken code managed O(n) due to -its brokenness.

A concrete example and extreme case is the "/sys" -hierarchy under Linux where some hundred devices exist under both -"/sys/devices" and "/sys/class" with the two sub-hierarchies -linking to the other, generating millions of legal paths to enumerate. -The structure, reduced to three devices, roughly looks like

-	/sys/class/tty/tty0 --> ../../dev/tty0
-	/sys/class/tty/tty1 --> ../../dev/tty1
-	/sys/class/tty/tty2 --> ../../dev/tty1
-	/sys/dev/tty0/bus
-	/sys/dev/tty0/subsystem --> ../../class/tty
-	/sys/dev/tty1/bus
-	/sys/dev/tty1/subsystem --> ../../class/tty
-	/sys/dev/tty2/bus
-	/sys/dev/tty2/subsystem --> ../../class/tty
-

The command fileutil::find currently has no way to escape -this. When having to handle such a pathological hierarchy It is -recommended to switch to package fileutil::traverse and the -same-named command it provides, and then use the -prefilter -option to prevent the traverser from following symbolic links, like so:

-    package require fileutil::traverse
-    proc NoLinks {fileName} {
-        if {[string equal [file type $fileName] link]} {
-            return 0
-        }
-        return 1
-    }
-    fileutil::traverse T /sys/devices -prefilter NoLinks
-    T foreach p {
-        puts $p
-    }
-    T destroy
-

Bugs, Ideas, Feedback

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

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

Keywords

cat, file utilities, grep, temp file, test, touch, type

Category

Programming tools

DELETED embedded/www/tcllib/files/modules/fileutil/multi.html Index: embedded/www/tcllib/files/modules/fileutil/multi.html ================================================================== --- embedded/www/tcllib/files/modules/fileutil/multi.html +++ /dev/null @@ -1,175 +0,0 @@ - -

- -

fileutil::multi(n) 0.1 tcllib "file utilities"

Name

fileutil::multi - Multi-file operation, scatter/gather, standard object

Table Of Contents
Synopsis
Description
PUBLIC API
Bugs, Ideas, Feedback
Keywords
Category

Synopsis

package require Tcl 8.4
package require fileutil::multi ?0.1?
package require fileutil::multi::op ?0.1?
package require wip ?1.0?

::fileutil::multi ?word...?

Description

This package provides a single command to perform actions on multiple -files selected by glob patterns. It is a thin layer over the package -fileutil::multi::op which provides objects for the -same. This package simply creates a single such object and directs all -file commands to it.

At the core is a domain specific language allowing the easy -specification of multi-file copy and/or move and/or deletion -operations. Alternate names would be scatter/gather processor, or -maybe even assembler. -For the detailed specification of this language, and examples, please -see the documention for the package fileutil::multi::op.

PUBLIC API

The main command of the package is:

::fileutil::multi ?word...?

This command interprets the specified words as file commands to -execute. See the section FILE API of the -documentation for the package fileutil::multi::op for -the set of acceptable commands, their syntax, and semantics.

The result of the command is the result generated by the last file -command it executed.

Bugs, Ideas, Feedback

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

Keywords

copy, file utilities, move, multi-file, remove

Category

Programming tools

DELETED embedded/www/tcllib/files/modules/fileutil/multiop.html Index: embedded/www/tcllib/files/modules/fileutil/multiop.html ================================================================== --- embedded/www/tcllib/files/modules/fileutil/multiop.html +++ /dev/null @@ -1,460 +0,0 @@ - -

- -

fileutil::multi::op(n) 0.5.3 tcllib "file utilities"

Name

fileutil::multi::op - Multi-file operation, scatter/gather

Table Of Contents
Synopsis
Description
CLASS API
OBJECT API
FILE API
EXAMPLES
Bugs, Ideas, Feedback
Keywords
Category

Synopsis

package require Tcl 8.4
package require fileutil::multi::op ?0.5.3?
package require wip ?1.0?

::fileutil::multi::op ?opName? ?word...?
opName option ?arg arg ...?
$opName do ?word...?
into directory
in directory
to directory
from directory
not pattern
for pattern
exclude pattern
but
except
as name
recursive
recursively
copy
move
remove
expand
invoke cmdprefix
reset
(
)
cd directory
up
for-windows
for-win
for-unix
the pattern
the-set varname
-> varname
strict
!strict
files
links
directories
dirs
all
state?
as?
excluded?
from?
into?
operation?
recursive?
strict?
type?

Description

This package provides objects which are able to perform actions on -multiple files selected by glob patterns.

CLASS API

The main command of the package is:

::fileutil::multi::op ?opName? ?word...?

The command creates a new multi-file operation object with an -associated global Tcl command whose name is opName. This -command can be used to invoke the various possible file operations. -It has the following general form:

opName option ?arg arg ...?: Option and the args determine the exact behavior of the -command.

If the string %AUTO% is used as the opName then the -package will generate a unique name on its own.

If one or more words are specified they are interpreted as an -initial set of file commands to execute. I.e. the method do -of the newly constructed object is implicitly invoked using the words -as its arguments.

OBJECT API

The following methods are possible for multi-file operation objects:

$opName do ?word...?

This method interprets the specified words as file commands to -execute. See the section FILE API for the set of -acceptable commands, their syntax, and semantics.

The result of the method is the result generated by the last file -command it executed.

FILE API

Both object constructor and method do take a list of words -and interpret them as file commands to execute. The names were chosen -to allow the construction of operations as sentences in near-natural -language. Most of the commands influence just the state of the object, -i.e. are simply providing the configuration used by the command -triggering the actual action.

into directory

Specifies the destination directory for operations.

in directory

Alias for into.

to directory

Alias for into.

from directory

Specifies the source directory for operations.

not pattern

Specifies a glob pattern for paths to be excluded from the operation.

for pattern

Alias for not.

exclude pattern

Alias for not.

but

Has no arguments of its own, but looks ahead in the list of words and -executes all not commands immediately following it. This allows the -construction of "but not" and "but exclude" clauses for a more natural -sounding specification of excluded paths.

except

A semi-alias for but. Has no arguments of its own, but looks -ahead in the list of words and executes all for commands -immediately following it. This allows the construction of "except for" -clauses for a more natural sounding specification of excluded paths.

as name

Specifies a new name for the first file handled by the current -operation. I.e. for the renaming of a single file during the -operation.

recursive

Signals that file expansion should happen in the whole directory -hierarchy and not just the directory itself.

recursively

An alias for recursive.

copy

Signals that the operation is the copying of files from source to -destination directory per the specified inclusion and exclusion -patterns.

move

Signals that the operation is the moving of files from source to -destination directory per the specified inclusion and exclusion -patterns.

remove

Signals that the operation is the removal of files in the destination -directory per the specified inclusion and exclusion patterns.

expand

Signals that there is no operation but the calculation of the set of -files from the include and exclude patterns. This operation is not -available if the-set is used.

invoke cmdprefix

Signals that the user-specified command prefix cmdprefix is the -operation to perform. The command prefix is executed at the global -level and given the source directory, destination directory, and set -of files (as dictionary mapping from source to destination files), in -this order.

reset

Forces the object into the ground state where all parts of the -configuration have default values.

(

Saves a copy of the current object state on a stack.

)

Takes the state at the top of the state stack and restores it, -i.e. makes it the new current object state.

cd directory

Changes the destination directory to the sub-directory directory -of the current destination.

up

Changes the destination directory to the parent directory of the -current destination.

for-windows

Checks that Windows is the current platform. Aborts processing if not.

for-win

An alias for for-windows.

for-unix

Checks that Unix is the current platform. Aborts processing if not.

the pattern

This command specifies the files to operate on per a glob pattern, and -is also the active element, i.e. the command which actually performs -the specified operation. All the other commands only modified the -object state to set the operation up, but di nothing else.

To allow for a more natural sounding syntax this command also looks -ahead in the list of words looks and executes several commands -immediately following it before performing its own actions. -These commands are as, but, exclude, except, -from, and into (and aliases). That way these commands act -like qualifiers, and still take effect as if they had been written -before this command.

After the operation has been performed the object state the exclude -patterns and the alias name, if specified, are reset to their default -values (i.e. empty), but nothing else.

the-set varname

Like the, however the set of files to use is not specified -implicitly per a glob pattern, but contained and loaded from the -specified variable. The operation expand is not available -if this command is used.

-> varname

Saves the set of files from the last expansion into the specified -variable.

strict

Make file expansion and definition of destination directory (in -and aliases) strict, i.e. report errors for missing directories, and -empty expansion.

!strict

Complement of strict. A missing destination directory or empty -expansion are not reported as errors.

files

Limit the search to files. Default is to accept every type of path.

links

Limit the search to symbolic links. Default is to accept every type of path.

directories

Limit the search to directories. Default is to accept every type of path.

dirs

An alias for directories.

all

Accept all types of paths (default).

state?

Returns the current state of the object as dictionary. The dictionary keys and their meanings are:

as: Last setting made by as.
excluded: List of currently known exclusion patterns.
from: Current source directory, set by from.
into: Current destination directory, set by into (and aliases).
operation: Current operation to perform, set by copy, move, remove, expand, or invoke.
recursive: Current recursion status. Set/unset by recursive and !recursive.
strict: Current strictness. Set/unset by strict and !strict.
type: Current path type limiter. Set by either files, directories, links, or all.

as?

Returns the current alias name.

excluded?

Returns the current set of exclusion patterns.

from?

Returns the current source directory.

into?

Returns the current destination directory.

operation?

Returns the current operation to perform.

recursive?

Returns the current recursion status.

strict?

Returns the current strictness.

type?

Returns the current path type limiter.

EXAMPLES

The following examples assume that the variable F contains a -reference to a multi-file operation object.

-    $F do copy                       \\
-	the  *.dll                    \\
-	from c:/TDK/PrivateOpenSSL/bin \\
-	to   [installdir_of tls]
-

-    $F do move      \\
-	the  *       \\
-	from /sources \\
-	into /scratch  \\
-	but not *.html
-    # Alternatively use 'except for *.html'.
-

-    $F do           \\
-	move         \\
-	the  index    \\
-	from /sources  \\
-	into /scratch   \\
-	as   pkgIndex.tcl
-

-    $F do         \\
-	remove     \\
-	the *.txt  \\
-	in /scratch
-

Note that the fact that most commands just modify the object state -allows us to use more off forms as specifications instead of just -nearly-natural language sentences. -For example the second example in this section can re-arranged into:

-    $F do            \\
-	from /sources \\
-	into /scratch  \\
-	but not *.html \\
-	move           \\
-	the  *
-

and the result is not only still a valid specification, but even stays -relatively readable.

Further note that the information collected by the commands but, -except, and as is automatically reset after the associated -the was executed. However no other state is reset in that -manner, allowing the user to avoid repetitions of unchanging -information. For example the second and third examples of this section -can be merged and rewritten into the equivalent:

-$F do                   \\
-    move                 \\
-    the  *                \\
-    from /sources          \\
-    into /scratch           \\
-    but not *.html not index \\
-    the  index               \\
-    as   pkgIndex.tcl
-

Bugs, Ideas, Feedback

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

Keywords

copy, file utilities, move, multi-file, remove

Category

Programming tools

DELETED embedded/www/tcllib/files/modules/fileutil/traverse.html Index: embedded/www/tcllib/files/modules/fileutil/traverse.html ================================================================== --- embedded/www/tcllib/files/modules/fileutil/traverse.html +++ /dev/null @@ -1,285 +0,0 @@ - -

- -

fileutil_traverse(n) 0.6 tcllib "file utilities"

Name

fileutil_traverse - Iterative directory traversal

Table Of Contents
Synopsis
Description
OPTIONS
Warnings and Incompatibilities
Bugs, Ideas, Feedback
Keywords
Category

Synopsis

package require Tcl 8.3
package require fileutil::traverse ?0.6?
package require fileutil
package require control

::fileutil::traverse ?objectName? path ?option value...?
$traverser command ?arg arg ...?
$traverser files
$traverser foreach filevar script
$traverser next filevar

Description

This package provides objects for the programmable traversal of -directory hierarchies. -The main command exported by the package is:

::fileutil::traverse ?objectName? path ?option value...?

The command creates a new traversal object with an associated global -Tcl command whose name is objectName. This command may be used -to invoke various operations on the traverser. -If the string %AUTO% is used as the objectName then a -unique name will be generated by the package itself.

Regarding the recognized options see section OPTIONS. Note -that all these options can be set only during the creation of the -traversal object. Changing them later is not possible and causes -errors to be thrown if attempted.

The object command has the following general form:

$traverser command ?arg arg ...?: Command and its arguments determine the exact behavior of -the object.

The following commands are possible for traversal objects:

$traverser files

This method is the most highlevel one provided by traversal -objects. When invoked it returns a list containing the names of all -files and directories matching the current configuration of the -traverser.

$traverser foreach filevar script

The highlevel files method (see above) is based on this -mid-level method. When invoked it finds all files and directories -matching per the current configuration and executes the script -for each path. The current path under consideration is stored in the -variable named by filevar. Both variable and script live / are -executed in the context of the caller of the method. In the method -files the script simply saves the found paths into the list -to return.

$traverser next filevar

This is the lowest possible interface to the traverser, the core all -higher methods are built on. When invoked it returns a boolean value -indicating whether it found a path matching the current configuration -(True), or not (False). If a path was found it is -stored into the variable named by filevar, in the context of the -caller.

The foreach method simply calls this method in a loop -until it returned False. This method is exposed so that we are -also able to incrementally traverse a directory hierarchy in an -event-based manner.

Note that the traverser does follow symbolic links, except when -doing so would cause it to enter a link-cycle. In other words, the -command takes care to not lose itself in infinite loops upon -encountering circular link structures. Note that even links which are -not followed will still appear in the result.

OPTIONS

-prefilter command_prefix: This callback is executed for directories. Its result determines if -the traverser recurses into the directory or not. The default is to -always recurse into all directories. The callback is invoked with a -single argument, the absolute path of the directory, and has to -return a boolean value, True when the directory passes the -filter, and False if not.
-filter command_prefix: This callback is executed for all paths. Its result determines if the -current path is a valid result, and returned by next. The -default is to accept all paths as valid. The callback is invoked with -a single argument, the absolute path to check, and has to -return a boolean value, True when the path passes the filter, -and False if not.
-errorcmd command_prefix: This callback is executed for all paths the traverser has trouble -with. Like being unable to change into them, get their status, -etc. The default is to ignore any such problems. The callback is -invoked with a two arguments, the absolute path for which the -error occured, and the error message. Errors thrown by the filter -callbacks are handled through this callback too. Errors thrown by the -error callback itself are not caught and ignored, but allowed to pass -to the caller, i.e. however invoked the next. Any other -results from the callback are ignored.

Warnings and Incompatibilities

0.4.4

In this version the traverser's broken system for handling symlinks -was replaced with one working correctly and properly enumerating all -the legal non-cyclic paths under a base directory.

-	/sys/class/tty/tty0 --> ../../dev/tty0
-	/sys/class/tty/tty1 --> ../../dev/tty1
-	/sys/class/tty/tty2 --> ../../dev/tty1
-	/sys/dev/tty0/bus
-	/sys/dev/tty0/subsystem --> ../../class/tty
-	/sys/dev/tty1/bus
-	/sys/dev/tty1/subsystem --> ../../class/tty
-	/sys/dev/tty2/bus
-	/sys/dev/tty2/subsystem --> ../../class/tty
-

When having to handle such a pathological hierarchy it is -recommended to use the -prefilter option to prevent the -traverser from following symbolic links, like so:

-    package require fileutil::traverse
-    proc NoLinks {fileName} {
-        if {[string equal [file type $fileName] link]} {
-            return 0
-        }
-        return 1
-    }
-    fileutil::traverse T /sys/devices -prefilter NoLinks
-    T foreach p {
-        puts $p
-    }
-    T destroy
-

Bugs, Ideas, Feedback

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

Keywords

directory traversal, traversal

Category

Programming tools

DELETED embedded/www/tcllib/files/modules/ftp/ftp.html Index: embedded/www/tcllib/files/modules/ftp/ftp.html ================================================================== --- embedded/www/tcllib/files/modules/ftp/ftp.html +++ /dev/null @@ -1,446 +0,0 @@ - -

- -

ftp(n) 2.4.13 tcllib "ftp client"

Name

ftp - Client-side tcl implementation of the ftp protocol

Table Of Contents
Synopsis
Description
API
BUGS
Bugs, Ideas, Feedback
See Also
Keywords
Category

- -

Description

The ftp package provides the client side of the ftp protocol as -specified in RFC 959 (http://www.rfc-editor.org/rfc/rfc959.txt). -The package implements both active (default) and passive ftp sessions.

A new ftp session is started with the ::ftp::Open command. To -shutdown an existing ftp session use ::ftp::Close. All other -commands are restricted to usage in an an open ftp session. They will -generate errors if they are used out of context. The ftp package -includes file and directory manipulating commands for remote sites. To -perform the same operations on the local site use commands built into -the core, like cd or file.

The output of the package is controlled by two state variables, -::ftp::VERBOSE and ::ftp::DEBUG. Setting -::ftp::VERBOSE to "1" forces the package to show all responses -from a remote server. The default value is "0". Setting -::ftp::DEBUG to "1" enables debugging and forces the package to -show all return codes, states, state changes and "real" ftp -commands. The default value is "0".

The command ::ftp::DisplayMsg is used to show the different -messages from the ftp session. The setting of ::ftp::VERBOSE -determines if this command is called or not. The current -implementation of the command uses the log package of tcllib -to write the messages to their final destination. This means that the -behaviour of ::ftp::DisplayMsg can be customized without -changing its implementation. For more radical changes overwriting its -implementation by the application is of course still possible. Note -that the default implementation honors the option -output to -::ftp::Open for a session specific log command.

Caution: The default implementation logs error messages like -all other messages. If this behaviour is changed to throwing an error -instead all commands in the API will change their behaviour too. In -such a case they will not return a failure code as described below but -pass the thrown error to their caller.

API

::ftp::Open server user passwd ?options?

This command is used to start a FTP session by establishing a control -connection to the FTP server. The defaults are used for any option not -specified by the caller.

The command takes a host name server, a user name user and -a password password as its parameters and returns a session -handle that is an integer number greater than or equal to "0", if the -connection is successfully established. Otherwise it returns "-1". -The server parameter must be the name or internet address (in -dotted decimal notation) of the ftp server to connect to. The -user and passwd parameters must contain a valid user name -and password to complete the login process.

The options overwrite some default values or set special abilities:

-blocksize size

The blocksize is used during data transfer. At most size bytes -are transfered at once. The default value for this option is 4096. -The package will evaluate the -progress callback for the -session after the transfer of each block.

-timeout seconds

If seconds is non-zero, then ::ftp::Open sets up a timeout -which will occur after the specified number of seconds. The default -value is 600.

-port number

The port number specifies an alternative remote port on the ftp -server on which the ftp service resides. Most ftp services listen for -connection requests on the default port 21. Sometimes, usually for -security reasons, port numbers other than 21 are used for ftp -connections.

-mode mode

The transfer mode option determines if a file transfer occurs in -active or passive mode. In passive mode the client -will ask the ftp server to listen on a data port and wait for the -connection rather than to initiate the process by itself when a data -transfer request comes in. Passive mode is normally a requirement when -accessing sites via a firewall. The default mode is active.

-progress callback

This callback is evaluated whenever a block of data was -transfered. See the option -blocksize for how to specify the -size of the transfered blocks.

When evaluating the callback one argument is appended to the -callback script, the current accumulated number of bytes transferred -so far.

-command callback

Specifying this option places the connection into asynchronous -mode. The callback is evaluated after the completion of any -operation. When an operation is running no further operations must be -started until a callback has been received for the currently executing -operation.

When evaluating the callback several arguments are appended to -the callback script, namely the keyword of the operation that has -completed and any additional arguments specific to the operation. If -an error occurred during the execution of the operation the callback is -given the keyword error.

-output callback

This option has no default. If it is set the default implementation of -::ftp::DisplayMsg will use its value as command prefix to log -all internal messages. The callback will have three arguments appended -to it before evaluation, the id of the session, the message itself, -and the connection state, in this order.

::ftp::Close handle

This command terminates the specified ftp session. If no file transfer -is in progress, the server will close the control connection -immediately. If a file transfer is in progress however, the control -connection will remain open until the transfers completes. When that -happens the server will write the result response for the transfer to -it and close the connection afterward.

::ftp::Cd handle directory

This command changes the current working directory on the ftp server -to a specified target directory. The command returns 1 if the -current working directory was successfully changed to the specified -directory or 0 if it fails. The target directory can be

a subdirectory of the current directory,
Two dots, .. (as an indicator for the parent directory of -the current directory)
or a fully qualified path to a new working directory.

::ftp::Pwd handle

This command returns the complete path of the current working -directory on the ftp server, or an empty string in case of an error.

::ftp::Type handle ?ascii|binary|tenex?

This command sets the ftp file transfer type to either ascii, -binary, or tenex. The command always returns the -currently set type. If called without type no change is made.

Currently only ascii and binary types are -supported. There is some early (alpha) support for Tenex mode. The -type ascii is normally used to convert text files into a -format suitable for text editors on the platform of the destination -machine. This mainly affects end-of-line markers. The type -binary on the other hand allows the undisturbed transfer of -non-text files, such as compressed files, images and executables.

::ftp::List handle ?pattern?

This command returns a human-readable list of files. Wildcard -expressions such as "*.tcl" are allowed. If pattern -refers to a specific directory, then the contents of that directory -are returned. If the pattern is not a fully-qualified path -name, the command lists entries relative to the current remote -directory. If no pattern is specified, the contents of the -current remote directory is returned.

The listing includes any system-dependent information that the server -chooses to include. For example most UNIX systems produce output from -the command ls -l. The command returns the retrieved -information as a tcl list with one item per entry. Empty lines and -UNIX's "total" lines are ignored and not included in the result as -reported by this command.

If the command fails an empty list is returned.

::ftp::NList handle ?directory?

This command has the same behavior as the ::ftp::List command, -except that it only retrieves an abbreviated listing. This means only -file names are returned in a sorted list.

::ftp::FileSize handle file

This command returns the size of the specified file on the ftp -server. If the command fails an empty string is returned.

ATTENTION! It will not work properly when in ascii mode and -is not supported by all ftp server implementations.

::ftp::ModTime handle file

This command retrieves the time of the last modification of the -file on the ftp server as a system dependent integer value in -seconds or an empty string if an error occurred. Use the built-in -command clock to convert the retrieves value into other formats.

::ftp::Delete handle file

This command deletes the specified file on the ftp server. The -command returns 1 if the specified file was successfully deleted or 0 -if it failed.

::ftp::Rename handle from to

This command renames the file from in the current directory of -the ftp server to the specified new file name to. This new file -name must not be the same as any existing subdirectory or file name. -The command returns 1 if the specified file was successfully renamed -or 0 if it failed.

::ftp::Put handle (local | -data data | -channel chan) ?remote?

This command transfers a local file local to a remote file -remote on the ftp server. If the file parameters passed to the -command do not fully qualified path names the command will use the -current directory on local and remote host. If the remote file name is -unspecified, the server will use the name of the local file as the -name of the remote file. The command returns 1 to indicate a successful -transfer and 0 in the case of a failure.

If -data data is specified instead of a local file, the -system will not transfer a file, but the data passed into it. In -this case the name of the remote file has to be specified.

If -channel chan is specified instead of a local file, -the system will not transfer a file, but read the contents of the -channel chan and write this to the remote file. In this case the -name of the remote file has to be specified. After the transfer -chan will be closed.

::ftp::Append handle (local | -data data | -channel chan) ?remote?

This command behaves like ::ftp::Puts, but appends the -transfered information to the remote file. If the file did not exist -on the server it will be created.

::ftp::Get handle remote ?(local | -variable varname | -channel chan)?

This command retrieves a remote file remote on the ftp server -and stores its contents into the local file local. If the file -parameters passed to the command are not fully qualified path names -the command will use the current directory on local and remote -host. If the local file name is unspecified, the server will use the -name of the remote file as the name of the local file. The command -returns 1 to indicate a successful transfer and 0 in the case of a -failure. The command will throw an error if the directory the file -local is to be placed in does not exist.

If -variable varname is specified, the system will -store the retrieved data into the variable varname instead of a -file.

If -channel chan is specified, the system will write -the retrieved data into the channel chan instead of a file. The -system will not close chan after the transfer, this is -the responsibility of the caller to ::ftp::Get.

::ftp::Reget handle remote ?local? ?from? ?to?

This command behaves like ::ftp::Get, except that if local file -local exists and is smaller than remote file remote, the -local file is presumed to be a partially transferred copy of the -remote file and the transfer is continued from the apparent point of -failure. The command will throw an error if the directory the file -local is to be placed in does not exist. This command is useful -when transferring very large files over networks that tend to drop -connections.

Specifying the additional byte offsets from and to will -cause the command to change its behaviour and to download exactly the -specified slice of the remote file. This mode is possible only if a -local destination is explicitly provided. Omission of to leads -to downloading till the end of the file.

::ftp::Newer handle remote ?local?

This command behaves like ::ftp::Get, except that it retrieves -the remote file only if the modification time of the remote file is -more recent than the file on the local system. If the file does not -exist on the local system, the remote file is considered newer. The -command will throw an error if the directory the file local is -to be placed in does not exist.

::ftp::MkDir handle directory

This command creates the specified directory on the ftp -server. If the specified path is relative the new directory will be -created as a subdirectory of the current working directory. Else the -created directory will have the specified path name. The command -returns 1 to indicate a successful creation of the directory and 0 in -the case of a failure.

::ftp::RmDir handle directory

This command removes the specified directory on the ftp server. The -remote directory has to be empty or the command will fail. The command -returns 1 to indicate a successful removal of the directory and 0 in -the case of a failure.

::ftp::Quote handle arg1 arg2 ...

This command is used to send an arbitrary ftp command to the -server. It cannot be used to obtain a directory listing or for -transferring files. It is included to allow an application to execute -commands on the ftp server which are not provided by this package. -The arguments are sent verbatim, i.e. as is, with no changes.

In contrast to the other commands in this package this command will -not parse the response it got from the ftp server but return it -verbatim to the caller.

::ftp::DisplayMsg handle msg ?state?

This command is used by the package itself to show the different -messages from the ftp sessions. The package itself declares this -command very simple, writing the messages to stdout (if -::ftp::VERBOSE was set, see below) and throwing tcl errors for -error messages. It is the responsibility of the application to -overwrite it as needed. A state variable for different states assigned -to different colors is recommended by the author. The package -log is useful for this.

::ftp::VERBOSE

A state variable controlling the output of the package. Setting -::ftp::VERBOSE to "1" forces the package to show all responses -from a remote server. The default value is "0".

::ftp::DEBUG

A state variable controlling the output of ftp. Setting -::ftp::DEBUG to "1" enables debugging and forces the package to -show all return codes, states, state changes and "real" ftp -commands. The default value is "0".

BUGS

The correct execution of many commands depends upon the proper -behavior by the remote server, network and router configuration.

An update command placed in the procedure ::ftp::DisplayMsg may -run into persistent errors or infinite loops. The solution to this -problem is to use update idletasks instead of update.

Bugs, Ideas, Feedback

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

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

Keywords

ftp, internet, net, rfc 959

Category

Networking

DELETED embedded/www/tcllib/files/modules/ftp/ftp_geturl.html Index: embedded/www/tcllib/files/modules/ftp/ftp_geturl.html ================================================================== --- embedded/www/tcllib/files/modules/ftp/ftp_geturl.html +++ /dev/null @@ -1,176 +0,0 @@ - -

- -

ftp::geturl(n) 0.2.2 tcllib "ftp client"

Name

ftp::geturl - Uri handler for ftp urls

Table Of Contents
Synopsis
Description
API
Bugs, Ideas, Feedback
See Also
Keywords
Category

Synopsis

package require Tcl 8.2
package require ftp::geturl ?0.2.2?

::ftp::geturl url

Description

This package provides a command which wraps around the client side of -the ftp protocol provided by package ftp to allow the -retrieval of urls using the ftp schema.

API

::ftp::geturl url

This command can be used by the generic command ::uri::geturl -(See package uri) to retrieve the contents of ftp -urls. Internally it uses the commands of the package ftp to -fulfill the request.

The contents of a ftp url are defined as follows:

file: The contents of the specified file itself.
directory: A listing of the contents of the directory in key value notation where -the file name is the key and its attributes the associated value.
link: The attributes of the link, including the path it refers to.

Bugs, Ideas, Feedback

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

Keywords

ftp, internet, net, rfc 959

Category

Networking

DELETED embedded/www/tcllib/files/modules/ftpd/ftpd.html Index: embedded/www/tcllib/files/modules/ftpd/ftpd.html ================================================================== --- embedded/www/tcllib/files/modules/ftpd/ftpd.html +++ /dev/null @@ -1,344 +0,0 @@ - -

- -

ftpd(n) 1.3 tcllib "Tcl FTP Server Package"

Name

ftpd - Tcl FTP server implementation

Table Of Contents
Synopsis
Description
COMMANDS
CALLBACKS
VARIABLES
Bugs, Ideas, Feedback
Keywords
Category

Synopsis

package require Tcl 8.3
package require ftpd ?1.3?

::ftpd::server ?myaddr?
::ftpd::config ?option value? ?option value ...?
fsCmd append path
fsCmd delete path channel
fsCmd dlist path style channel
fsCmd exists path
fsCmd mkdir path channel
fsCmd mtime path channel
fsCmd permissions path
fsCmd rename path newpath channel
fsCmd retr path
fsCmd rmdir path channel
fsCmd size path channel
fsCmd store path

Description

The ftpd package provides a simple Tcl-only server library -for the FTP protocol as specified in -RFC 959 (http://www.rfc-editor.org/rfc/rfc959.txt). -It works by listening on the standard FTP socket. Most server errors -are returned as error messages with the appropriate code attached to -them. Since the server code for the ftp daemon is executed in the -event loop, it is possible that a -bgerror will be thrown on the server if there are problems with -the code in the module.

COMMANDS

::ftpd::server ?myaddr?

Open a listening socket to listen to and accept ftp connections. -myaddr is an optional argument. myaddr is the domain-style name -or numerical IP address of the client-side network interface to use -for the connection.

::ftpd::config ?option value? ?option value ...?

The value is always the name of the command to call as the -callback. The option specifies which callback should be configured. -See section CALLBACKS for descriptions of the arguments and -return values for each of the callbacks.

-authIpCmd proc: Callback to authenticate new connections based on the ip-address of -the peer.
-authUsrCmd proc: Callback to authenticate new connections based on the user logging in -(and the users password).
-authFileCmd proc: Callback to accept or deny a users access to read and write to a -specific path or file.
-logCmd proc: Callback for log information generated by the FTP engine.
-fsCmd proc: Callback to connect the engine to the filesystem it operates on.
-closeCmd proc: Callback to be called when a connection is closed. This allows the -embedding application to perform its own cleanup operations.
-xferDoneCmd proc: Callback for transfer completion notification. In other words, it is -called whenever a transfer of data to or from the client has -completed.

CALLBACKS

authIpCmd callback

The authIpCmd receives the ip-address of the peer attempting to -connect to the ftp server as its argument. It returns a 1 to allow -users from the specified IP to attempt to login and a 0 to reject the -login attempt from the specified IP.

authUsrCmd callback

The authUsrCmd receives the username and password as its two -arguments. It returns a 1 to accept the attempted login to the ftpd -and a 0 to reject the attempted login.

authFileCmd callback

The authFileCmd receives the user (that is currently logged in), the -path or filename that is about to be read or written, and -read or write as its three arguments. It returns a -1 to allow the path or filename to be read or written, and a 0 to -reject the attempted read or write with a permissions error code.

logCmd callback

The logCmd receives a severity and a message as its two arguments. -The severities used within the ftpd package are note, -debug, and error. The logCmd doesn't return -anything.

fsCmd callback

The fsCmd receives a subcommand, a filename or path, and optional -additional arguments (depending on the subcommand).

The subcommands supported by the fsCmd are:

fsCmd append path: The append subcommand receives the filename to append to as its -argument. It returns a writable tcl channel as its return value.
fsCmd delete path channel: The delete subcommand receives the filename to delete, and a channel -to write to as its two arguments. The file specified is deleted and -the appropriate ftp message is written to the channel that is passed -as the second argument. The delete subcommand returns nothing.
fsCmd dlist path style channel: The dlist subcommand receives the path that it should list the files -that are in, the style in which the files should be listed which is -either nlst or list, and a channel to write to as -its three arguments. The files in the specified path are printed to -the specified channel one per line. If the style is nlst -only the name of the file is printed to the channel. If the style is -list then the file permissions, number of links to the file, -the name of the user that owns the file, the name of the group that -owns the file, the size (in bytes) of the file, the modify time of the -file, and the filename are printed out to the channel in a formatted -space separated format. The dlist subcommand returns -nothing.
fsCmd exists path: The exists subcommand receives the name of a file to check the -existence of as its only argument. The exists subcommand returns a 1 -if the path specified exists and the path is not a directory.
fsCmd mkdir path channel: The mkdir subcommand receives the path of a directory to create and a -channel to write to as its two arguments. The mkdir subcommand -creates the specified directory if necessary and possible. The mkdir -subcommand then prints the appropriate success or failure message to -the channel. The mkdir subcommand returns nothing.
fsCmd mtime path channel: The mtime subcommand receives the path of a file to check the modify -time on and a channel as its two arguments. If the file exists the -mtime is printed to the channel in the proper FTP format, otherwise an -appropriate error message and code are printed to the channel. The -mtime subcommand returns nothing.
fsCmd permissions path: The permissions subcommand receives the path of a file to retrieve the -permissions of. The permissions subcommand returns the octal file -permissions of the specified file. The file is expected to exist.
fsCmd rename path newpath channel: The rename subcommand receives the path of the current file, the new -file path, and a channel to write to as its three arguments. The -rename subcommand renames the current file to the new file path if the -path to the new file exists, and then prints out the appropriate -message to the channel. If the new file path doesn't exist the -appropriate error message is printed to the channel. The rename -subcommand returns nothing.
fsCmd retr path: The retr subcommand receives the path of a file to read as its only -argument. The retr subcommand returns a readable channel that the -specified file can be read from.
fsCmd rmdir path channel: The rmdir subcommand receives the path of a directory to remove and a -channel to write to as its two arguments. The rmdir subcommand -removes the specified directory (if possible) and prints the -appropriate message to the channel (which may be an error if the -specified directory does not exist or is not empty). The rmdir -subcommand returns nothing.
fsCmd size path channel: The size subcommand receives the path of a file to get the size (in -bytes) of and a channel to write to as its two arguments. The size -subcommand prints the appropriate code and the size of the file if the -specified path is a file, otherwise an appropriate error code and -message are printed to the channel. The size subcommand returns -nothing.
fsCmd store path: The store subcommand receives the path of a file to write as its only -argument. The store subcommand returns a writable channel.

closeCmd

The closeCmd receives no arguments when it is invoked, and any -return value it may generate is discarded.

xferDoneCmd sock sock2 file bytes filename err

The xferDoneCmd receives six arguments when invoked. These are, -in this order, the channel handle of the control socket for the -connection, the channel handle of the data socket used for the -transfer (already closed), the handle of the channel containing the -transfered file, the number of bytes transfered, the path of the file -which was transfered, and a (possibly empty) error message. -Any return value it may generate is discarded.

VARIABLES

::ftpd::cwd: The current working directory for a session when someone first -connects to the FTPD or when the REIN ftp command is received.
::ftpd::contact: The e-mail address of the person that is the contact for the ftp -server. This address is printed out as part of the response to the -FTP HELP command.
::ftpd::port: The port that the ftp server should listen on. -If port is specified as zero, the operating system will allocate an -unused port for use as a server socket; afterwards, the variable will -contain the port number that was allocated.
::ftpd::welcome: The message that is printed out when the user first connects to the -ftp server.
::ftpd::CurrentSocket: Accessible to all callbacks and all filesystem commands (which are a -special form of callback) and contains the handle of the socket -channel which was active when the callback was invoked.

Bugs, Ideas, Feedback

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

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

Keywords

ftp, ftpd, ftpserver, rfc 959, services

Category

Networking

DELETED embedded/www/tcllib/files/modules/fumagic/cfront.html Index: embedded/www/tcllib/files/modules/fumagic/cfront.html ================================================================== --- embedded/www/tcllib/files/modules/fumagic/cfront.html +++ /dev/null @@ -1,188 +0,0 @@ - -

- -

fileutil::magic::cfront(n) 1.2.0 tcllib "file utilities"

Name

fileutil::magic::cfront - Generator core for compiler of magic(5) files

Table Of Contents
Synopsis
Description
COMMANDS
Bugs, Ideas, Feedback
See Also
Keywords
Category

Synopsis

package require Tcl 8.5
package require fileutil::magic::cfront ?1.2.0?
package require fileutil::magic::cgen ?1.2.0?
package require fileutil::magic::rt ?1.2.0?
package require struct::list
package require fileutil

::fileutil::magic::cfront::compile path...
::fileutil::magic::cfront::procdef procname path...
::fileutil::magic::cfront::install path...

Description

This package provides the frontend of a compiler of magic(5) files -into recognizers based on the fileutil::magic::rt recognizer -runtime package. For the generator backed used by this compiler see -the package fileutil::magic::cgen.

COMMANDS

::fileutil::magic::cfront::compile path...

This command takes the paths of one or more files and directories and -compiles all the files, and the files in all the directories into a -single recognizer for all the file types specified in these files.

All the files have to be in the format specified by magic(5).

The result of the command is a Tcl script containing the generated -recognizer.

::fileutil::magic::cfront::procdef procname path...

This command behaves like ::fileutil::magic::cfront::compile -with regard to the specified path arguments, then wraps the resulting -recognizer script into a procedure named procname, puts code -setting up the namespace of procname in front, and returns the -resulting script.

::fileutil::magic::cfront::install path...

This command uses ::fileutil::magic::cfront::procdef to compile -each of the paths into a recognizer procedure and installs the result -in the current interpreter.

The name of each new procedure is derived from the name of the -file/directory used in its creation, with file/directory "FOO" -causing the creation of procedure ::fileutil::magic::/FOO::run.

Bugs, Ideas, Feedback

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

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

Keywords

file recognition, file type, file utilities, mime, type

Category

Programming tools

DELETED embedded/www/tcllib/files/modules/fumagic/cgen.html Index: embedded/www/tcllib/files/modules/fumagic/cgen.html ================================================================== --- embedded/www/tcllib/files/modules/fumagic/cgen.html +++ /dev/null @@ -1,184 +0,0 @@ - -

- -

fileutil::magic::cgen(n) 1.2.0 tcllib "file utilities"

Name

fileutil::magic::cgen - Generator core for compiler of magic(5) files

Table Of Contents
Synopsis
Description
COMMANDS
Bugs, Ideas, Feedback
See Also
Keywords
Category

Synopsis

package require Tcl 8.4
package require fileutil::magic::cgen ?1.2.0?
package require fileutil::magic::rt ?1.2.0?
package require struct::tree
package require struct::list

::fileutil::magic::cgen::2tree script
::fileutil::magic::cgen::treedump tree
::fileutil::magic::cgen::treegen tree node

Description

This package provides the generator backend for a compiler of magic(5) -files into recognizers based on the fileutil::magic::rt -recognizer runtime package. For the compiler frontend using this -generator see the package fileutil::magic::cfront.

COMMANDS

::fileutil::magic::cgen::2tree script

This command converts the recognizer specified by the script -into a tree and returns the object command of that tree as its -result. It uses the package struct::tree for the tree.

The script is in the format specified by magic(5).

::fileutil::magic::cgen::treedump tree

This command takes a tree as generated by -::fileutil::magic::cgen::2tree and returns a string encoding the -tree for human consumption, to aid in debugging.

::fileutil::magic::cgen::treegen tree node

This command takes a tree as generated by -::fileutil::magic::cgen::2tree and returns a Tcl script, the -recognizer for the file types represented by the sub-tree rooted at -the node. -The generated script makes extensive use of the commands provided by -the recognizer runtime package fileutil::magic::rt to -perform its duties.

Bugs, Ideas, Feedback

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

Keywords

file recognition, file type, file utilities, mime, type

Category

Programming tools

DELETED embedded/www/tcllib/files/modules/fumagic/filetypes.html Index: embedded/www/tcllib/files/modules/fumagic/filetypes.html ================================================================== --- embedded/www/tcllib/files/modules/fumagic/filetypes.html +++ /dev/null @@ -1,176 +0,0 @@ - -

- -

fileutil::magic::filetype(n) 2.0 tcllib "file utilities"

Name

fileutil::magic::filetype - Procedures implementing file-type recognition

Table Of Contents
Synopsis
Description
REFERENCES
Bugs, Ideas, Feedback
See Also
Keywords
Category

Synopsis

package require Tcl 8.6
package require fileutil::magic::filetype ?2.0?

::fileutil::magic::filetype filename

Description

This package provides a command for the recognition of file types in -pure Tcl.

The core part of the recognizer was generated from a "magic(5)" file -containing the checks to perform to recognize files, and associated -file-types.

Beware! This recognizer is large, about 752 Kilobyte of -generated Tcl code.

::fileutil::magic::filetype filename

This command is similar to the command fileutil::fileType.

Returns a list containing a list of descriptions, a list of mimetype -components, and a list file extensions. Returns an empty string if the file -content is not recognized.

REFERENCES

File(1) sources -This site contains the current sources for the file command, including -the magic definitions used by it. The latter were used by us to -generate this recognizer.

Bugs, Ideas, Feedback

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

Keywords

file recognition, file type, file utilities, type

Category

Programming tools

DELETED embedded/www/tcllib/files/modules/fumagic/rtcore.html Index: embedded/www/tcllib/files/modules/fumagic/rtcore.html ================================================================== --- embedded/www/tcllib/files/modules/fumagic/rtcore.html +++ /dev/null @@ -1,333 +0,0 @@ - -

- -

fileutil::magic::rt(n) 2.0 tcllib "file utilities"

Name

fileutil::magic::rt - Runtime core for file type recognition engines written in pure Tcl

Table Of Contents
Synopsis
Description
COMMANDS
NUMERIC TYPES
Bugs, Ideas, Feedback
See Also
Keywords
Category

Synopsis

package require Tcl 8.5
package require fileutil::magic::rt ?2.0?

::fileutil::magic::rt::>
::fileutil::magic::rt::<
::fileutil::magic::rt::open filename
::fileutil::magic::rt::close
::fileutil::magic::rt::file_start name
::fileutil::magic::rt::result ?msg?
::fileutil::magic::rt::resultv ?msg?
::fileutil::magic::rt::emit msg
::fileutil::magic::rt::offset where
::fileutil::magic::rt::Nv type offset ?qual?
::fileutil::magic::rt::N type offset comp val ?qual?
::fileutil::magic::rt::Nvx type offset ?qual?
::fileutil::magic::rt::Nx type offset comp val ?qual?
::fileutil::magic::rt::S offset comp val ?qual?
::fileutil::magic::rt::Sx offset comp val ?qual?
::fileutil::magic::rt::L newlevel
::fileutil::magic::rt::I base type delta
::fileutil::magic::rt::R offset
::fileutil::magic::rt::U fileindex name

Description

This package provides the runtime core for file type recognition -engines written in pure Tcl and is thus used by all other packages in -this module, i.e. the two frontend packages -fileutil::magic::mimetypes and -fileutil::magic::filetypes, and the two engine compiler -packages fileutil::magic::cgen and -fileutil::magic::cfront.

COMMANDS

::fileutil::magic::rt::>

Shorthand for incr level.

::fileutil::magic::rt::<

Shorthand for incr level -1.

::fileutil::magic::rt::open filename

This command initializes the runtime and prepares the file -filename for use by the system. -This command has to be invoked first, before any other command of this -package.

The command returns the channel handle of the opened file as its -result.

::fileutil::magic::rt::close

This command closes the last file opened via -::fileutil::magic::rt::open and shuts the runtime down. -This command has to be invoked last, after the file has been dealt -with completely. -Afterward another invokation of ::fileutil::magic::rt::open is -required to process another file.

This command returns the empty string as its result.

::fileutil::magic::rt::file_start name

This command marks the start of a magic file when debugging. It -returns the empty string as its result.

::fileutil::magic::rt::result ?msg?

This command returns the current result and stops processing.

If msg is specified its text is added to the result before it is -returned. See ::fileutil::magic::rt::emit for the allowed -special character sequences.

::fileutil::magic::rt::resultv ?msg?

This command returns the current result. -In contrast to ::fileutil::magic::rt::result processing -continues.

If msg is specified its text is added to the result before it is -returned. See ::fileutil::magic::rt::emit for the allowed -special character sequences.

::fileutil::magic::rt::emit msg

This command adds the text msg to the result buffer. The -message may contain the following special character sequences. They -will be replaced with buffered values before the message is added to -the result. The command returns the empty string as its result.

\b: This sequence is removed
%s: Replaced with the last buffered string value.
%ld: Replaced with the last buffered numeric value.
%d: See above.

::fileutil::magic::rt::Nv type offset ?qual?

This command fetches the numeric value with type from the -absolute location offset and returns it as its result. The -fetched value is further stored in the numeric buffer.

If qual is specified it is considered to be a mask and applied -to the fetched value before it is stored and returned. It has to have -the form of a partial Tcl bit-wise expression, i.e.

-	& number
-

For example:

-	Nv lelong 0 &0x8080ffff
-

For the possible types see section NUMERIC TYPES.

::fileutil::magic::rt::N type offset comp val ?qual?

This command behaves mostly like ::fileutil::magic::rt::Nv, -except that it compares the fetched and masked value against val -as specified with comp and returns the result of that -comparison.

The argument comp has to contain one of Tcl's comparison -operators, and the comparison made will be

-	<val> <comp> <fetched-and-masked-value>
-

The special comparison operator x signals that no comparison -should be done, or, in other words, that the fetched value will always -match val.

::fileutil::magic::rt::Nvx type offset ?qual?

This command behaves like ::fileutil::magic::rt::Nv, except that -it additionally remembers the location in the file after the fetch in -the calling context, for the current level, for later use by -::fileutil::magic::rt::R.

::fileutil::magic::rt::Nx type offset comp val ?qual?

This command behaves like ::fileutil::magic::rt::N, except that -it additionally remembers the location in the file after the fetch in -the calling context, for the current, for later use by -::fileutil::magic::rt::R.

::fileutil::magic::rt::S offset comp val ?qual?

This command behaves like ::fileutil::magic::rt::N, except that -it fetches and compares strings, not numeric data. The fetched value -is also stored in the internal string buffer instead of the numeric -buffer.

::fileutil::magic::rt::Sx offset comp val ?qual?

This command behaves like ::fileutil::magic::rt::S, except that -it additionally remembers the location in the file after the fetch in -the calling context, for the current level, for later use by -::fileutil::magic::rt::R.

::fileutil::magic::rt::L newlevel

This command sets the current level in the calling context to -newlevel. The command returns the empty string as its result.

::fileutil::magic::rt::I base type delta

This command handles base locations specified indirectly through the -contents of the inspected file. It returns the sum of delta and -the value of numeric type fetched from the absolute location -base.

For the possible types see section NUMERIC TYPES.

::fileutil::magic::rt::R offset

This command handles base locations specified relative to the end of -the last field one level above.

In other words, the command computes an absolute location in the file -based on the relative offset and returns it as its result. The -base the offset is added to is the last location remembered for the -level in the calling context.

::fileutil::magic::rt::U fileindex name

Use a named test script at the current level.

NUMERIC TYPES

byte: 8-bit integer
short: 16-bit integer, stored in native endianess
beshort: see above, stored in big endian
leshort: see above, stored in small/little endian
long: 32-bit integer, stored in native endianess
belong: see above, stored in big endian
lelong: see above, stored in small/little endian

All of the types above exit in an unsigned form as well. The type -names are the same, with the character "u" added as prefix.

date: 32-bit integer timestamp, stored in native endianess
bedate: see above, stored in big endian
ledate: see above, stored in small/little endian
ldate: 32-bit integer timestamp, stored in native endianess
beldate: see above, stored in big endian
leldate: see above, stored in small/little endian

Bugs, Ideas, Feedback

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

Keywords

file recognition, file type, file utilities, mime, type

Category

Programming tools

DELETED embedded/www/tcllib/files/modules/generator/generator.html Index: embedded/www/tcllib/files/modules/generator/generator.html ================================================================== --- embedded/www/tcllib/files/modules/generator/generator.html +++ /dev/null @@ -1,506 +0,0 @@ -

- -

generator(n) 0.1 tcllib "Tcl Generator Commands"

Name

generator - Procedures for creating and using generators.

Table Of Contents
Synopsis
Description
COMMANDS
PRELUDE
BUGS, IDEAS, FEEDBACK
Keywords

Synopsis

package require Tcl 8.6
package require generator ?0.1?

generator define name params body
generator yield arg ?args..?
generator foreach varList generator varList generator ?...? body
generator next generator ?varName..?
generator exists generator
generator names
generator destroy ?generator..?
generator finally cmd ?arg..?
generator from format value
generator to format generator
generator map function generator
generator filter predicate generator
generator reduce function zero generator
generator foldl function zero generator
generator foldr function zero generator
generator all predicate generator
generator and generator
generator any generator
generator concat generator ?generator..?
generator concatMap function generator
generator drop n generator
generator dropWhile predicate generator
generator contains element generator
generator foldl1 function generator
generator foldli function zero generator
generator foldri function zero generator
generator head generator
generator tail generator
generator init generator
generator takeList n generator
generator take n generator
generator iterate function init
generator last generator
generator length generator
generator or predicate generator
generator product generator
generator repeat n value..
generator sum generator
generator takeWhile predicate generator
generator splitWhen predicate generator
generator scanl function zero generator

Description

The generator package provides commands to define and iterate over -generator expressions. A generator is a command that returns a sequence -of values. However, unlike an ordinary command that returns a list, a -generator yields each value and then suspends, allowing subsequent -values to be fetched on-demand. As such, generators can be used to efficiently -iterate over a set of values, without having to generate all answers in-memory. -Generators can be used to iterate over elements of a data structure, or rows -in the result set of a database query, or to decouple producer/consumer software -designs such as parsers and tokenizers, or to implement sophisticated custom -control strategies such as backtracking search. Generators reduce the need to -implement custom control structures, as many such structures can be recast as -generators, leading to both a simpler implementation and a more standardised -interface. The generator mechanism is built on top of the Tcl 8.6 coroutine -mechanism.

The package exports a single ensemble command, generator. All -functionality is provided as subcommands of this command. The core subcommands -of the package are define, yield, and foreach. The -define command works like Tcl's proc command, but creates a -generator procedure; that is, a procedure that returns a generator when called. -The generator itself is a command that can be called multiple times: each time -it returns the next value in the generated series. When the -series has been exhausted, the generator command returns an empty list and then -destroys itself. Rather than manually call a generator, however, the package -also provides a flexible foreach command that loops through the values of -one or more generators. This loop construct mimicks the functionality of the -built-in Tcl foreach command, including handling multiple return values -and looping over multiple generators at once. Writing a generator is also a -simple task, much like writing a normal procedure: simply use the define -command to define the generator, and then call yield instead of return. -For example, we can define a generator for looping through the integers -in a particular range:

-    generator define range {n m} {
-        for {set i $n} {$i <= $m} {incr i} { generator yield $i }
-    }
-    generator foreach x [range 1 10] {
-        puts "x = $x"
-    }
-

The above example will print the numbers from 1 to 10 in sequence, as you would -expect. The difference from a normal loop over a list is that the numbers are -only generated as they are needed. If we insert a break into the loop then any -remaining numbers in the sequence would never be generated. To illustrate, we -can define a generator that produces the sequence of natural numbers: an -infinite series. A normal procedure would never return trying to produce this -series as a list. By using a generator we only have to generate those values -which are actually used:

-    generator define nats {} {
-        while 1 { generator yield [incr nat] }
-    }
-    generator foreach n [nats] {
-        if {$n > 100} { break }
-    }
-

COMMANDS

generator define name params body

Creates a new generator procedure. The arguments to the command are identical to -those for proc: a name, a list of parameters, and a body. The -parameter list format is identical to a procedure. In particular, default values -and the ?args? syntax can be used as usual. Each time the resulting -generator procedure is called it creates a new generator command (coroutine) -that will yield a list of values on each call. Each result from a generator is -guaranteed to be a non-empty list of values. When a generator is exhausted it -returns an empty list and then destroys itself to free up resources. It is an -error to attempt to call an exhausted generator as the command no longer exists.

generator yield arg ?args..?

Used in the definition of a generator, this command returns the next set of -values to the consumer. Once the yield command has been called the -generator will suspend to allow the consumer to process that value. When the -next value is requested, the generator will resume as if the yield command had -just returned, and can continue processing to yield the next result. The -yield command must be called with at least one argument, but can be called with -multiple arguments, in which case this is equivalent to calling yield -once for each argument.

generator foreach varList generator varList generator ?...? body

Loops through one or more generators, assigning the next values to variables and -then executing the loop body. Works much like the built-in foreach -command, but working with generators rather than lists. Multiple generators can -be iterated over in parallel, and multiple results can be retrieved from a -single generator at once. Like the built-in foreach, the loop will -continue until all of the generators have been exhausted: variables for -generators that are exhausted early will be set to the empty string.

The foreach command will automatically clean-up all of the generators -at the end of the loop, regardless of whether the loop terminated early or not. -This behaviour is provided as a convenience to avoid having to explicitly -clean up a generator in the usual cases. Generators can however be destroyed -before the end of the loop, in which case the loop will continue as normal until -all the other generators have been destroyed or exhausted.

The foreach command does not take a snapshot of the generator. Any -changes in the state of the generator made inside the loop or by other code will -affect the state of the loop. In particular, if the code in the loop invokes the -generator to manually retrieve the next element, this element will then be -excluded from the loop, and the next iteration will continue from the element -after that one. Care should be taken to avoid concurrent updates to generators -unless this behaviour is required (e.g., in argument processing).

generator next generator ?varName..?

Manually retrieves the next values from a generator. One value is retrieved for -each variable supplied and assigned to the corresponding variable. If the -generator becomes exhausted at any time then any remaining variables are set to -the empty string.

generator exists generator

Returns 1 if the generator (still) exists, or 0 otherwise.

generator names

Returns a list of all currently existing generator commands.

generator destroy ?generator..?

Destroys one or more generators, freeing any associated resources.

generator finally cmd ?arg..?

Used in the definition of a generator procedure, this command arranges for a -resource to be cleaned up whenever the generator is destroyed, either explicitly -or implicitly when the generator is exhausted. This command can be used like a -finally block in the try command, except that it is tied to the -life-cycle of the generator rather than to a particular scope. For example, if -we create a generator to iterate over the lines in a text file, we can use -finally to ensure that the file is closed whenever the generator is -destroyed:

-    generator define lines file {
-        set in [open $file]
-        # Ensure file is always closed
-        generator finally close $in
-        while {[gets $in line] >= 0} {
-            generator yield $line
-        }
-    }
-    generator foreach line [lines /etc/passwd] {
-        puts "[incr count]: $line"
-        if {$count > 10} { break }
-    }
-    # File will be closed even on early exit
-

If you create a generator that consumes another generator (such as the standard -map and filter generators defined later), then you should use -a finally command to ensure that this generator is destroyed when its -parent is. For example, the map generator is defined as follows:

-    generator define map {f xs} {
-        generator finally generator destroy $xs
-        generator foreach x $xs { generator yield [{*}$f $x] }
-    }
-

generator from format value

Creates a generator from a data structure. Currently, supported formats are -list, dict, or string. The list format yields each -element in turn. For dictionaries, each key and value are yielded separately. -Finally, strings are yielded a character at a time.

generator to format generator

Converts a generator into a data structure. This is the reverse operation of the -from command, and supports the same data structures. The two operations -obey the following identity laws (where = is interpreted -appropriately):

-    [generator to $fmt [generator from $fmt $value]] = $value
-    [generator from $fmt [generator to $fmt $gen]]   = $gen
-

PRELUDE

The following commands are provided as a standard library of generator -combinators and functions that perform convenience operations on generators. The -functions in this section are loosely modelled on the equivalent functions from -the Haskell Prelude. Warning: most of the functions in this prelude -destroy any generator arguments they are passed as a side-effect. If you want to -have persistent generators, see the streams library.

generator map function generator

Apply a function to every element of a generator, returning a new generator of -the results. This is the classic map function from functional programming, -applied to generators. For example, we can generate all the square numbers using -the following code (where nats is defined as earlier):

-    proc square x { expr {$x * $x} }
-    generator foreach n [generator map square [nats]] {
-        puts "n = $n"
-        if {$n > 1000} { break }
-    }
-

generator filter predicate generator

Another classic functional programming gem. This command returns a generator -that yields only those items from the argument generator that satisfy the -predicate (boolean function). For example, if we had a generator employees -that returned a stream of dictionaries representing people, we could filter all -those whose salaries are above 100,000 dollars (or whichever currency you prefer) -using a simple filter:

-    proc salary> {amount person} { expr {[dict get $person salary] > $amount} }
-    set fat-cats [generator filter {salary> 100000} $employees]
-

generator reduce function zero generator

This is the classic left-fold operation. This command takes a function, an -initial value, and a generator of values. For each element in the generator it -applies the function to the current accumulator value (the zero argument -initially) and that element, and then uses the result as the new accumulator -value. This process is repeated through the entire generator (eagerly) and the -final accumulator value is then returned. If we consider the function to be a -binary operator, and the zero argument to be the left identity element of that -operation, then we can consider the reduce command as folding -the operator between each successive pair of values in the generator in a -left-associative fashion. For example, the sum of a sequence of numbers can be -calculated by folding a + operator between them, with 0 as the identity:

-    # sum xs          = reduce + 0 xs
-    # sum [range 1 5] = reduce + 0 [range 1 5]
-    #                 = reduce + [+ 0 1] [range 2 5]
-    #                 = reduce + [+ 1 2] [range 3 5]
-    #                 = ...
-    #                 = reduce + [+ 10 5] <empty>
-    #                 = ((((0+1)+2)+3)+4)+5
-    #                 = 15
-    proc + {a b} { expr {$a + $b} }
-    proc sum gen { generator reduce + 0 $gen }
-    puts [sum [range 1 10]]
-

The reduce operation is an extremely useful one, and a great variety of -different operations can be defined using it. For example, we can define a -factorial function as the product of a range using generators. This definition -is both very clear and also quite efficient (in both memory and running time):

-    proc * {x y} { expr {$x * $y} }
-    proc prod gen { generator reduce * 0 $gen }
-    proc fac n { prod [range 1 $n] }
-

However, while the reduce operation is efficient for finite generators, -care should be taken not to apply it to an infinite generator, as this will -result in an infinite loop:

-    sum [nats]; # Never returns
-

generator foldl function zero generator

This is an alias for the reduce command.

generator foldr function zero generator

This is the right-associative version of reduce. This operation is -generally inefficient, as the entire generator needs to be evaluated into memory -(as a list) before the reduction can commence. In an eagerly evaluated language -like Tcl, this operation has limited use, and should be avoided if possible.

generator all predicate generator

Returns true if all elements of the generator satisfy the given predicate.

generator and generator

Returns true if all elements of the generator are true (i.e., takes the logical -conjunction of the elements).

generator any generator

Returns true if any of the elements of the generator are true (i.e., logical -disjunction).

generator concat generator ?generator..?

Returns a generator which is the concatenation of each of the argument -generators.

generator concatMap function generator

Given a function which maps a value to a series of values, and a generator of -values of that type, returns a generator of all of the results in one flat -series. Equivalent to concat applied to the result of map.

generator drop n generator

Removes the given number of elements from the front of the generator and returns -the resulting generator with those elements removed.

generator dropWhile predicate generator

Removes all elements from the front of the generator that satisfy the predicate.

generator contains element generator

Returns true if the generator contains the given element. Note that this will -destroy the generator!

generator foldl1 function generator

A version of foldl that takes the zero argument from the first -element of the generator. Therefore this function is only valid on non-empty -generators.

generator foldli function zero generator

A version of foldl that supplies the integer index of each element as -the first argument to the function. The first element in the generator at this -point is given index 0.

generator foldri function zero generator

Right-associative version of foldli.

generator head generator

Returns the first element of the generator.

generator tail generator

Removes the first element of the generator, returning the rest.

generator init generator

Returns a new generator consisting of all elements except the last of the -argument generator.

generator takeList n generator

Returns the next n elements of the generator as a list. If not enough -elements are left in the generator, then just the remaining elements are -returned.

generator take n generator

Returns the next n elements of the generator as a new generator. The old -generator is destroyed.

generator iterate function init

Returns an infinite generator formed by repeatedly applying the function to the -initial argument. For example, the Fibonacci numbers can be defined as follows:

-    proc fst pair { lindex $pair 0 }
-    proc snd pair { lindex $pair 1 }
-    proc nextFib ab { list [snd $ab] [expr {[fst $ab] + [snd $ab]}] }
-    proc fibs {} { generator map fst [generator iterate nextFib {0 1}] }
-

generator last generator

Returns the last element of the generator (if it exists).

generator length generator

Returns the length of the generator, destroying it in the process.

generator or predicate generator

Returns 1 if any of the elements of the generator satisfy the predicate.

generator product generator

Returns the product of the numbers in a generator.

generator repeat n value..

Returns a generator that consists of n copies of the given elements. The -special value Inf can be used to generate an infinite sequence.

generator sum generator

Returns the sum of the values in the generator.

generator takeWhile predicate generator

Returns a generator of the first elements in the argument generator that satisfy -the predicate.

generator splitWhen predicate generator

Splits the generator into lists of elements using the predicate to identify -delimiters. The resulting lists are returned as a generator. Elements matching -the delimiter predicate are discarded. For example, to split up a generator -using the string "|" as a delimiter:

-    set xs [generator from list {a | b | c}]
-    generator split {string equal "|"} $xs ;# returns a then b then c
-

generator scanl function zero generator

Similar to foldl, but returns a generator of all of the intermediate -values for the accumulator argument. The final element of this generator is -equivalent to foldl called on the same arguments.

BUGS, IDEAS, FEEDBACK

Please report any errors in this document, or in the package it describes, to -Neil Madden.

Keywords

control structure, coroutine, filter, foldl, foldr, foreach, generator, iterator, map, reduce, scanl

DELETED embedded/www/tcllib/files/modules/gpx/gpx.html Index: embedded/www/tcllib/files/modules/gpx/gpx.html ================================================================== --- embedded/www/tcllib/files/modules/gpx/gpx.html +++ /dev/null @@ -1,271 +0,0 @@ - -

- -

gpx(n) 0.9 tcllib "GPS eXchange Format (GPX)"

Name

gpx - Extracts waypoints, tracks and routes from GPX files

Table Of Contents
Synopsis
Description
COMMANDS
DATA STRUCTURES
EXAMPLE
REFERENCES
AUTHOR
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.5
package require gpx ?0.9?

::gpx::Create gpxFilename ?rawXML?
::gpx::Cleanup token
::gpx::GetGPXMetadata token
::gpx::GetWaypointCount token
::gpx::GetAllWaypoints token
::gpx::GetTrackCount token
::gpx::GetTrackMetadata token whichTrack
::gpx::GetTrackPoints token whichTrack
::gpx::GetRouteCount token
::gpx::GetRouteMetadata token whichRoute
::gpx::GetRoutePoints token whichRoute

Description

This module parses and extracts waypoints, tracks, routes and -metadata from a GPX (GPS eXchange) file. Both GPX version 1.0 -and 1.1 are supported.

COMMANDS

::gpx::Create gpxFilename ?rawXML?: The ::gpx::Create is the first command called to process GPX -data. It takes the GPX data from either the rawXML -parameter if present or from the contents of gpxFilename, -and parses it using tdom. It returns a token value that is used -by all the other commands.
::gpx::Cleanup token: This procedure cleans up resources associated with token. -It is strongly recommended that you call this -function after you are done with a given GPX file. -Not doing so will result in memory not being freed, and -if your app calls ::gpx::Create enough times, the -memory leak could cause a performance hit...or worse.
::gpx::GetGPXMetadata token: This procedure returns a dictionary of the metadata -associated with the GPX data identified by token. -The format of the metadata dictionary is described -below, but keys version and creator -will always be present.
::gpx::GetWaypointCount token: This procedure returns the number of waypoints defined in the GPX -data identified by token.
::gpx::GetAllWaypoints token: This procedure returns the a list of waypoints defined in the GPX -data identified by token. The format of each waypoint item -is described below.
::gpx::GetTrackCount token: This procedure returns the number of tracks defined in the GPX -data identified by token.
::gpx::GetTrackMetadata token whichTrack: This procedure returns a dictionary of the metadata -associated track number whichTrack (1 based) in -the GPX data identified by token. -The format of the metadata dictionary is described below.
::gpx::GetTrackPoints token whichTrack: The procedure returns a list of track points comprising track -number whichTrack (1 based) in the GPX data identified by -token. The format of the metadata dictionary is described below.
::gpx::GetRouteCount token: This procedure returns the number of routes defined in the GPX -data identified by token.
::gpx::GetRouteMetadata token whichRoute: This procedure returns a dictionary of the metadata -associated route number whichRoute (1 based) in -the GPX data identified by token. -The format of the metadata dictionary is described below.
::gpx::GetRoutePoints token whichRoute: The procedure returns a list of route points comprising route -number whichRoute (1 based) in the GPX data identified by -token. The format of the metadata dictionary is described below.

DATA STRUCTURES

metadata dictionary: The metadata associated with either the GPX document, a -track, a route, a waypoint, a track point or route -point is returned in a dictionary. The keys of that -dictionary will be whatever optional GPX elements are -present. The value for each key depends on the GPX schema -for that element. For example, the value for a version -key will be a string, while for a link key will be -a sub-dictionary with keys href and optionally -text and type.
point item: Each item in a track or route list of points consists of -a list of three elements: latitude, longitude and -metadata dictionary. Latitude and longitude -are decimal numbers. The metadata dictionary format is -described above. For points in a track, typically there will -always be ele (elevation) and time metadata keys.

EXAMPLE

-% set token [::gpx::Create myGpxFile.gpx]
-% set version [dict get [::gpx::GetGPXMetadata $token] version]
-% set trackCnt [::gpx::GetTrackCount $token]
-% set firstPoint [lindex [::gpx::GetTrackPoints $token 1] 0]
-% lassign $firstPoint lat lon ptMetadata
-% puts "first point in the first track is at $lat, $lon"
-% if {[dict exists $ptMetadata ele]} {
-     puts "at elevation [dict get $ptMetadata ele] meters"
-  }
-% ::gpx::Cleanup $token
-

REFERENCES

GPX: the GPS Exchange Format - (http://www.topografix.com/gpx.asp)
GPX 1.1 Schema Documentation (http://www.topografix.com/GPX/1/1/)
GPX 1.0 Developer's Manual (http://www.topografix.com/gpx_manual.asp)

AUTHOR

Keith Vetter

Bugs, Ideas, Feedback

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

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

Keywords

gps, gpx

Category

File formats

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_aycock/aycock.html Index: embedded/www/tcllib/files/modules/grammar_aycock/aycock.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_aycock/aycock.html +++ /dev/null @@ -1,240 +0,0 @@ - -

- -

grammar::aycock(n) 1.0 tcllib "Aycock-Horspool-Earley parser generator for Tcl"

Name

grammar::aycock - Aycock-Horspool-Earley parser generator for Tcl

Table Of Contents
Synopsis
Description
PROCEDURES
OBJECT COMMAND
DESCRIPTION
EXAMPLE
KEYWORDS
Keywords
Category
Copyright

Synopsis

package require Tcl 8.5
package require grammar::aycock ?1.0?

::aycock::parser grammar ?-verbose?
parserName parse symList valList ?clientData?
parserName destroy
parserName terminals
parserName nonterminals
parserName save

Description

The grammar::aycock package -implements a parser generator for the class of parsers described -in John Aycock and R. Nigel Horspool. Practical Earley Parsing. -The Computer Journal, 45(6):620-630, 2002. -http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.12.4254

PROCEDURES

The grammar::aycock package exports the single procedure:

::aycock::parser grammar ?-verbose?: Generates a parser for the given grammar, and returns its -name. If the optional -verbose flag is given, dumps verbose -information relating to the generated parser to the standard output. -The returned parser is an object that accepts commands as shown in -OBJECT COMMAND below.

OBJECT COMMAND

parserName parse symList valList ?clientData?: Invokes a parser returned from ::aycock::parser. symList is -a list of grammar symbols representing the terminals in an input -string, and valList is a list of their semantic values. The -result is the semantic value of the entire string when parsed.
parserName destroy: Destroys a parser constructed by ::aycock::parser.
parserName terminals: Returns a list of terminal symbols that may be presented in the -symList argument to the parse object command.
parserName nonterminals: Returns a list of nonterminal symbols that were defined in the -parser's grammar.
parserName save: Returns a Tcl script that will reconstruct the parser without -needing all the mechanism of the parser generator at run time. -The reconstructed parser depends on a set of commands in the -package grammar::aycock::runtime, -which is also automatically loaded -when the grammar::aycock package is loaded.

DESCRIPTION

The grammar::aycock::parser command accepts a grammar expressed as -a Tcl list. The list must be structured as the concatenation of a set -of rules. Each rule comprises a variable number of -elements in the list:

The name of the nonterminal symbol that the rule reduces.
The literal string, ::=
Zero or more names of terminal or nonterminal symbols that -comprise the right-hand-side of the rule.
Finally, a Tcl script to execute when the rule is reduced. -Within the given script, a variable called _ contains a list of -the semantic values of the symbols on the right-hand side. The value -returned by the script is expected to be the semantic value of the -left-hand side. If the clientData parameter was passed to the -parse method, it is available in a variable called -clientData. It is permissible for the script to be the empty -string. In this case, the semantic value of the rule will be the same -as the semantic value of the first symbol on the right-hand side. If -the right-hand side is also empty, the semantic value will be the -empty string.

Parsing is done with an Earley parser, which is not terribly efficient -in speed or memory consumption, but which deals effectively with -ambiguous grammars. For this reason, the grammar::aycock package is -perhaps best adapted to natural-language processing or the parsing of -extraordinarily complex languages in which ambiguity can be tolerated.

EXAMPLE

The following code demonstrates a trivial desk calculator, admitting -only +, * and parentheses as its operators. It also -shows the format in which the lexical analyzer is expected to present -terminal symbols to the parser.

-set p [aycock::parser {
-    start ::= E {}
-    E ::= E + T {expr {[lindex $_ 0] + [lindex $_ 2]}}
-    E ::= T {}
-    T ::= T * F {expr {[lindex $_ 0] * [lindex $_ 2]}}
-    T ::= F {}
-    F ::= NUMBER {}
-    F ::= ( E ) {lindex $_ 1}
-}]
-puts [$p parse {(  NUMBER +  NUMBER )  *  ( NUMBER +  NUMBER ) }  {{} 2      {} 3      {} {} {} 7     {} 1      {}}]
-$p destroy
-

The example, when run, prints 40.

KEYWORDS

Aycock, Earley, Horspool, parser, compiler

Keywords

ambiguous, aycock, earley, grammar, horspool, parser, parsing, transducer

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_fa/dacceptor.html Index: embedded/www/tcllib/files/modules/grammar_fa/dacceptor.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_fa/dacceptor.html +++ /dev/null @@ -1,208 +0,0 @@ - -

- -

grammar::fa::dacceptor(n) 0.1.1 tcllib "Finite automaton operations and usage"

Name

grammar::fa::dacceptor - Create and use deterministic acceptors

Table Of Contents
Synopsis
Description
API
ACCEPTOR METHODS
EXAMPLES
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require snit
package require struct::set
package require grammar::fa::dacceptor ?0.1.1?

::grammar::fa::dacceptor daName fa ?-any any?
daName option ?arg arg ...?
daName destroy
daName accept? symbols

Description

This package provides a class for acceptors constructed from -deterministic finite automatons (DFA). Acceptors are objects -which can be given a string of symbols and tell if the DFA they are -constructed from would accept that string. -For the actual creation of the DFAs the acceptors are based on we have -the packages grammar::fa and grammar::fa::op.

API

The package exports the API described here.

::grammar::fa::dacceptor daName fa ?-any any?

Creates a new deterministic acceptor with an associated global Tcl command -whose name is daName. This command may be used to invoke various -operations on the acceptor. It has the following general form:

daName option ?arg arg ...?

Option and the args determine the exact behavior of the -command. See section ACCEPTOR METHODS for more explanations.

The acceptor will be based on the deterministic finite automaton -stored in the object fa. It will keep a copy of the relevant -data of the FA in its own storage, in a form easy to use for its -purposes. This also means that changes made to the fa after the -construction of the acceptor will not influence the acceptor.

If any has been specified, then the acceptor will convert all -symbols in the input which are unknown to the base FA to that symbol -before proceeding with the processing.

ACCEPTOR METHODS

All acceptors provide the following methods for their manipulation:

daName destroy: Destroys the automaton, including its storage space and associated -command.
daName accept? symbols: Takes the list of symbols and checks if the FA the acceptor is -based on would accept it. The result is a boolean value. True -is returned if the symbols are accepted, and False -otherwise. Note that bogus symbols in the input are either translated -to the any symbol (if specified), or cause the acceptance test -to simply fail. No errors will be thrown. The method will process only -just that prefix of the input which is enough to fully determine -(non-)acceptance.

EXAMPLES

Bugs, Ideas, Feedback

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

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

Keywords

acceptance, acceptor, automaton, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, state, transducer

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_fa/dexec.html Index: embedded/www/tcllib/files/modules/grammar_fa/dexec.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_fa/dexec.html +++ /dev/null @@ -1,265 +0,0 @@ - -

- -

grammar::fa::dexec(n) 0.2 tcllib "Finite automaton operations and usage"

Name

grammar::fa::dexec - Execute deterministic finite automatons

Table Of Contents
Synopsis
Description
API
EXECUTOR METHODS
EXECUTOR CALLBACK
EXAMPLES
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require snit
package require grammar::fa::dexec ?0.2?

::grammar::fa::dexec daName fa ?-any any? ?-command cmdprefix?
daName option ?arg arg ...?
daName destroy
daName put symbol
daName reset
daName state
cmdprefix error code message
cmdprefix final stateid
cmdprefix reset
cmdprefix state stateid

Description

This package provides a class for executors constructed from -deterministic finite automatons (DFA). Executors are objects -which are given a string of symbols in a piecemal fashion, perform -state transitions and report back when they enter a final state, or -find an error in the input. -For the actual creation of the DFAs the executors are based on we have -the packages grammar::fa and grammar::fa::op.

The objects follow a push model. Symbols are pushed into the executor, -and when something important happens, i.e. error occurs, a state transition, -or a final state is entered this will be reported via the callback -specified via the option -command. Note that conversion of -this into a pull model where the environment retrieves messages from -the object and the object uses a callback to ask for more symbols is -a trivial thing.

Side note: -The acceptor objects provided by grammar::fa::dacceptor -could have been implemented on top of the executors provided here, but -were not, to get a bit more performance (we avoid a number of method -calls and the time required for their dispatch).

API

The package exports the API described here.

::grammar::fa::dexec daName fa ?-any any? ?-command cmdprefix?

Creates a new deterministic executor with an associated global Tcl -command whose name is daName. This command may be used to invoke -various operations on the executor. It has the following general form:

daName option ?arg arg ...?

Option and the args determine the exact behavior of the -command. See section EXECUTOR METHODS for more -explanations.

The executor will be based on the deterministic finite automaton -stored in the object fa. It will keep a copy of the relevant -data of the FA in its own storage, in a form easy to use for its -purposes. This also means that changes made to the fa after the -construction of the executor will not influence the executor.

If any has been specified, then the executor will convert all -symbols in the input which are unknown to the base FA to that symbol -before proceeding with the processing.

EXECUTOR METHODS

All executors provide the following methods for their manipulation:

daName destroy

Destroys the automaton, including its storage space and associated -command.

daName put symbol

Takes the current state of the executor and the symbol and -performs the appropriate state transition. Reports any errors -encountered via the command callback, as well as entering a final -state of the underlying FA.

When an error is reported all further invokations of put will -do nothing, until the error condition has been cleared via an -invokation of method reset.

daName reset

Unconditionally sets the executor into the start state of the -underlying FA. This also clears any error condition put may -have encountered.

daName state

Returns the current state of the underlying FA. This allow for -introspection without the need to pass data from the callback command.

EXECUTOR CALLBACK

The callback command cmdprefix given to an executor via the -option -command will be executed by the object at the global -level, using the syntax described below. Note that cmdprefix is -not simply the name of a command, but a full command prefix. In other -words it may contain additional fixed argument words beyond the -command word.

cmdprefix error code message

The executor has encountered an error, and message contains a -human-readable text explaining the nature of the problem. -The code on the other hand is a fixed machine-readable text. -The following error codes can be generated by executor objects.

BADSYM: An unknown symbol was found in the input. This can happen if and only -if no -any symbol was specified.
BADTRANS: The underlying FA has no transition for the current combination of -input symbol and state. In other words, the executor was not able to -compute a new state for this combination.

cmdprefix final stateid

The executor has entered the final state stateid.

cmdprefix reset

The executor was reset.

cmdprefix state stateid

The FA changed state due to a transition. stateid is the new state.

EXAMPLES

Bugs, Ideas, Feedback

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

Keywords

automaton, execution, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, running, state, transducer

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_fa/fa.html Index: embedded/www/tcllib/files/modules/grammar_fa/fa.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_fa/fa.html +++ /dev/null @@ -1,628 +0,0 @@ - -

- -

grammar::fa(n) 0.4 tcllib "Finite automaton operations and usage"

Name

grammar::fa - Create and manipulate finite automatons

Table Of Contents
Synopsis
Description
API
FA METHODS
EXAMPLES
FINITE AUTOMATONS
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require snit 1.3
package require struct::list
package require struct::set
package require grammar::fa::op ?0.2?
package require grammar::fa ?0.4?

::grammar::fa faName ?=|:=|<--|as|deserialize src|fromRegex re ?over??
faName option ?arg arg ...?
faName destroy
faName clear
faName = srcFA
faName --> dstFA
faName serialize
faName deserialize serialization
faName states
faName state add s1 ?s2 ...?
faName state delete s1 ?s2 ...?
faName state exists s
faName state rename s snew
faName startstates
faName start add s1 ?s2 ...?
faName start remove s1 ?s2 ...?
faName start? s
faName start?set stateset
faName finalstates
faName final add s1 ?s2 ...?
faName final remove s1 ?s2 ...?
faName final? s
faName final?set stateset
faName symbols
faName symbols@ s ?d?
faName symbols@set stateset
faName symbol add sym1 ?sym2 ...?
faName symbol delete sym1 ?sym2 ...?
faName symbol rename sym newsym
faName symbol exists sym
faName next s sym ?--> next?
faName !next s sym ?--> next?
faName nextset stateset sym
faName is deterministic
faName is complete
faName is useful
faName is epsilon-free
faName reachable_states
faName unreachable_states
faName reachable s
faName useful_states
faName unuseful_states
faName useful s
faName epsilon_closure s
faName reverse
faName complete
faName remove_eps
faName trim ?what?
faName determinize ?mapvar?
faName minimize ?mapvar?
faName complement
faName kleene
faName optional
faName union fa ?mapvar?
faName intersect fa ?mapvar?
faName difference fa ?mapvar?
faName concatenate fa ?mapvar?
faName fromRegex regex ?over?

Description

This package provides a container class for -finite automatons (Short: FA). -It allows the incremental definition of the automaton, its -manipulation and querying of the definition. -While the package provides complex operations on the automaton -(via package grammar::fa::op), it does not have the -ability to execute a definition for a stream of symbols. -Use the packages -grammar::fa::dacceptor and -grammar::fa::dexec for that. -Another package related to this is grammar::fa::compiler. It -turns a FA into an executor class which has the definition of the FA -hardwired into it. The output of this package is configurable to suit -a large number of different implementation languages and paradigms.

For more information about what a finite automaton is see section -FINITE AUTOMATONS.

API

The package exports the API described here.

::grammar::fa faName ?=|:=|<--|as|deserialize src|fromRegex re ?over??

Creates a new finite automaton with an associated global Tcl command -whose name is faName. This command may be used to invoke various -operations on the automaton. It has the following general form:

faName option ?arg arg ...?: Option and the args determine the exact behavior of the -command. See section FA METHODS for more explanations. The -new automaton will be empty if no src is specified. Otherwise -it will contain a copy of the definition contained in the src. -The src has to be a FA object reference for all operators except -deserialize and fromRegex. The deserialize -operator requires src to be the serialization of a FA instead, -and fromRegex takes a regular expression in the form a of a -syntax tree. See ::grammar::fa::op::fromRegex for more detail on -that.

FA METHODS

All automatons provide the following methods for their manipulation:

faName destroy

Destroys the automaton, including its storage space and associated -command.

faName clear

Clears out the definition of the automaton contained in faName, -but does not destroy the object.

faName = srcFA

Assigns the contents of the automaton contained -in srcFA to faName, overwriting any -existing definition. -This is the assignment operator for automatons. It copies the -automaton contained in the FA object srcFA over the automaton -definition in faName. The old contents of faName are -deleted by this operation.

This operation is in effect equivalent to

-    faName deserialize [srcFA serialize]
-

faName --> dstFA

This is the reverse assignment operator for automatons. It copies the -automation contained in the object faName over the automaton -definition in the object dstFA. -The old contents of dstFA are deleted by this operation.

This operation is in effect equivalent to

-    dstFA deserialize [faName serialize]
-

faName serialize

This method serializes the automaton stored in faName. In other -words it returns a tcl value completely describing that -automaton. -This allows, for example, the transfer of automatons over arbitrary -channels, persistence, etc. -This method is also the basis for both the copy constructor and the -assignment operator.

The result of this method has to be semantically identical over all -implementations of the grammar::fa interface. This is what -will enable us to copy automatons between different implementations of -the same interface.

The result is a list of three elements with the following structure:

The constant string grammar::fa.
A list containing the names of all known input symbols. The order of -elements in this list is not relevant.
The last item in the list is a dictionary, however the order of the -keys is important as well. The keys are the states of the serialized -FA, and their order is the order in which to create the states when -deserializing. This is relevant to preserve the order relationship -between states.
-
The value of each dictionary entry is a list of three elements -describing the state in more detail.
-
1. A boolean flag. If its value is true then the state is a -start state, otherwise it is not.
2. A boolean flag. If its value is true then the state is a -final state, otherwise it is not.
3. The last element is a dictionary describing the transitions for the -state. The keys are symbols (or the empty string), and the values are -sets of successor states.
-

Assuming the following FA (which describes the life of a truck driver -in a very simple way :)

-    Drive -- yellow --> Brake -- red --> (Stop) -- red/yellow --> Attention -- green --> Drive
-    (...) is the start state.
-

a possible serialization is

-    grammar::fa \\
-    {yellow red green red/yellow} \\
-    {Drive     {0 0 {yellow     Brake}} \\
-     Brake     {0 0 {red        Stop}} \\
-     Stop      {1 0 {red/yellow Attention}} \\
-     Attention {0 0 {green      Drive}}}
-

A possible one, because I did not care about creation order here

faName deserialize serialization

This is the complement to serialize. It replaces the -automaton definition in faName with the automaton described by -the serialization value. The old contents of faName are -deleted by this operation.

faName states

Returns the set of all states known to faName.

faName state add s1 ?s2 ...?

Adds the states s1, s2, et cetera to the FA definition in -faName. The operation will fail any of the new states is already -declared.

faName state delete s1 ?s2 ...?

Deletes the state s1, s2, et cetera, and all associated -information from the FA definition in faName. The latter means -that the information about in- or outbound transitions is deleted as -well. If the deleted state was a start or final state then this -information is invalidated as well. The operation will fail if the -state s is not known to the FA.

faName state exists s

A predicate. It tests whether the state s is known to the FA in -faName. -The result is a boolean value. It will be set to true if the -state s is known, and false otherwise.

faName state rename s snew

Renames the state s to snew. Fails if s is not a -known state. Also fails if snew is already known as a state.

faName startstates

Returns the set of states which are marked as start states, -also known as initial states. -See FINITE AUTOMATONS for explanations what this means.

faName start add s1 ?s2 ...?

Mark the states s1, s2, et cetera in the FA faName -as start (aka initial).

faName start remove s1 ?s2 ...?

Mark the states s1, s2, et cetera in the FA faName -as not start (aka not accepting).

faName start? s

A predicate. It tests if the state s in the FA faName is -start or not. -The result is a boolean value. It will be set to true if the -state s is start, and false otherwise.

faName start?set stateset

A predicate. It tests if the set of states stateset contains at -least one start state. They operation will fail if the set contains an -element which is not a known state. -The result is a boolean value. It will be set to true if a -start state is present in stateset, and false otherwise.

faName finalstates

Returns the set of states which are marked as final states, -also known as accepting states. -See FINITE AUTOMATONS for explanations what this means.

faName final add s1 ?s2 ...?

Mark the states s1, s2, et cetera in the FA faName -as final (aka accepting).

faName final remove s1 ?s2 ...?

Mark the states s1, s2, et cetera in the FA faName -as not final (aka not accepting).

faName final? s

A predicate. It tests if the state s in the FA faName is -final or not. -The result is a boolean value. It will be set to true if the -state s is final, and false otherwise.

faName final?set stateset

A predicate. It tests if the set of states stateset contains at -least one final state. They operation will fail if the set contains an -element which is not a known state. -The result is a boolean value. It will be set to true if a -final state is present in stateset, and false otherwise.

faName symbols

Returns the set of all symbols known to the FA faName.

faName symbols@ s ?d?

Returns the set of all symbols for which the state s has transitions. -If the empty symbol is present then s has epsilon transitions. If two -states are specified the result is the set of symbols which have transitions -from s to t. This set may be empty if there are no transitions -between the two specified states.

faName symbols@set stateset

Returns the set of all symbols for which at least one state in the set -of states stateset has transitions. -In other words, the union of [faName symbols@ s] -for all states s in stateset. -If the empty symbol is present then at least one state contained in -stateset has epsilon transitions.

faName symbol add sym1 ?sym2 ...?

Adds the symbols sym1, sym2, et cetera to the FA -definition in faName. The operation will fail any of the symbols -is already declared. The empty string is not allowed as a value for the symbols.

faName symbol delete sym1 ?sym2 ...?

Deletes the symbols sym1, sym2 et cetera, and all -associated information from the FA definition in faName. The -latter means that all transitions using the symbols are deleted as -well. The operation will fail if any of the symbols is not known to -the FA.

faName symbol rename sym newsym

Renames the symbol sym to newsym. Fails if sym is -not a known symbol. Also fails if newsym is already known as a -symbol.

faName symbol exists sym

A predicate. It tests whether the symbol sym is known to the FA -in faName. -The result is a boolean value. It will be set to true if the -symbol sym is known, and false otherwise.

faName next s sym ?--> next?

Define or query transition information.

If next is specified, then the method will add a transition from -the state s to the successor state next labeled with -the symbol sym to the FA contained in faName. The -operation will fail if s, or next are not known states, or -if sym is not a known symbol. An exception to the latter is that -sym is allowed to be the empty string. In that case the new -transition is an epsilon transition which will not consume -input when traversed. The operation will also fail if the combination -of (s, sym, and next) is already present in the FA.

If next was not specified, then the method will return -the set of states which can be reached from s through -a single transition labeled with symbol sym.

faName !next s sym ?--> next?

Remove one or more transitions from the Fa in faName.

If next was specified then the single transition from the state -s to the state next labeled with the symbol sym is -removed from the FA. Otherwise all transitions originating in -state s and labeled with the symbol sym will be removed.

The operation will fail if s and/or next are not known as -states. It will also fail if a non-empty sym is not known as -symbol. The empty string is acceptable, and allows the removal of -epsilon transitions.

faName nextset stateset sym

Returns the set of states which can be reached by a single transition -originating in a state in the set stateset and labeled with the -symbol sym.

In other words, this is the union of -[faName next s symbol] -for all states s in stateset.

faName is deterministic

A predicate. It tests whether the FA in faName is a -deterministic FA or not. -The result is a boolean value. It will be set to true if the -FA is deterministic, and false otherwise.

faName is complete

A predicate. It tests whether the FA in faName is a complete FA -or not. A FA is complete if it has at least one transition per state -and symbol. This also means that a FA without symbols, or states is -also complete. -The result is a boolean value. It will be set to true if the -FA is deterministic, and false otherwise.

Note: When a FA has epsilon-transitions transitions over a symbol for -a state S can be indirect, i.e. not attached directly to S, but to a -state in the epsilon-closure of S. The symbols for such indirect -transitions count when computing completeness.

faName is useful

A predicate. It tests whether the FA in faName is an useful FA -or not. A FA is useful if all states are reachable -and useful. -The result is a boolean value. It will be set to true if the -FA is deterministic, and false otherwise.

faName is epsilon-free

A predicate. It tests whether the FA in faName is an -epsilon-free FA or not. A FA is epsilon-free if it has no epsilon -transitions. This definition means that all deterministic FAs are -epsilon-free as well, and epsilon-freeness is a necessary -pre-condition for deterministic'ness. -The result is a boolean value. It will be set to true if the -FA is deterministic, and false otherwise.

faName reachable_states

Returns the set of states which are reachable from a start state by -one or more transitions.

faName unreachable_states

Returns the set of states which are not reachable from any start state -by any number of transitions. This is

-	 [faName states] - [faName reachable_states]
-

faName reachable s

A predicate. It tests whether the state s in the FA faName -can be reached from a start state by one or more transitions. -The result is a boolean value. It will be set to true if the -state can be reached, and false otherwise.

faName useful_states

Returns the set of states which are able to reach a final state by -one or more transitions.

faName unuseful_states

Returns the set of states which are not able to reach a final state by -any number of transitions. This is

-	 [faName states] - [faName useful_states]
-

faName useful s

A predicate. It tests whether the state s in the FA faName -is able to reach a final state by one or more transitions. -The result is a boolean value. It will be set to true if the -state is useful, and false otherwise.

faName epsilon_closure s

Returns the set of states which are reachable from the state s -in the FA faName by one or more epsilon transitions, i.e -transitions over the empty symbol, transitions which do not consume -input. This is called the epsilon closure of s.

faName reverse

faName complete

faName remove_eps

faName trim ?what?

faName determinize ?mapvar?

faName minimize ?mapvar?

faName complement

faName kleene

faName optional

faName union fa ?mapvar?

faName intersect fa ?mapvar?

faName difference fa ?mapvar?

faName concatenate fa ?mapvar?

faName fromRegex regex ?over?

These methods provide more complex operations on the FA. Please see -the same-named commands in the package grammar::fa::op for -descriptions of what they do.

EXAMPLES

FINITE AUTOMATONS

For the mathematically inclined, a FA is a 5-tuple (S,Sy,St,Fi,T) where

S is a set of states,
Sy a set of input symbols,
St is a subset of S, the set of start states, also known as -initial states.
Fi is a subset of S, the set of final states, also known as -accepting.
T is a function from S x (Sy + epsilon) to {S}, the transition function. -Here epsilon denotes the empty input symbol and is distinct -from all symbols in Sy; and {S} is the set of subsets of S. In other -words, T maps a combination of State and Input (which can be empty) to -a set of successor states.

In computer theory a FA is most often shown as a graph where the nodes -represent the states, and the edges between the nodes encode the -transition function: For all n in S' = T (s, sy) we have one edge -between the nodes representing s and n resp., labeled with sy. The -start and accepting states are encoded through distinct visual -markers, i.e. they are attributes of the nodes.

FA's are used to process streams of symbols over Sy.

A specific FA is said to accept a finite stream sy_1 sy_2 -... sy_n if there is a path in the graph of the FA beginning at a -state in St and ending at a state in Fi whose edges have the labels -sy_1, sy_2, etc. to sy_n. -The set of all strings accepted by the FA is the language of -the FA. One important equivalence is that the set of languages which -can be accepted by an FA is the set of regular languages.

Another important concept is that of deterministic FAs. A FA is said -to be deterministic if for each string of input symbols there -is exactly one path in the graph of the FA beginning at the start -state and whose edges are labeled with the symbols in the string. -While it might seem that non-deterministic FAs to have more power of -recognition, this is not so. For each non-deterministic FA we can -construct a deterministic FA which accepts the same language (--> -Thompson's subset construction).

While one of the premier applications of FAs is in parsing, -especially in the lexer stage (where symbols == characters), -this is not the only possibility by far.

Quite a lot of processes can be modeled as a FA, albeit with a -possibly large set of states. For these the notion of accepting states -is often less or not relevant at all. What is needed instead is the -ability to act to state changes in the FA, i.e. to generate some -output in response to the input. -This transforms a FA into a finite transducer, which has an -additional set OSy of output symbols and also an additional -output function O which maps from "S x (Sy + epsilon)" to -"(Osy + epsilon)", i.e a combination of state and input, possibly -empty to an output symbol, or nothing.

For the graph representation this means that edges are additional -labeled with the output symbol to write when this edge is traversed -while matching input. Note that for an application "writing an output -symbol" can also be "executing some code".

Transducers are not handled by this package. They will get their own -package in the future.

Bugs, Ideas, Feedback

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

Keywords

automaton, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, state, transducer

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_fa/faop.html Index: embedded/www/tcllib/files/modules/grammar_fa/faop.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_fa/faop.html +++ /dev/null @@ -1,464 +0,0 @@ - -

- -

grammar::fa::op(n) 0.4 tcllib "Finite automaton operations and usage"

Name

grammar::fa::op - Operations on finite automatons

Table Of Contents
Synopsis
Description
API
EXAMPLES
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require snit
package require struct::list
package require struct::set
package require grammar::fa::op ?0.4.1?

::grammar::fa::op::constructor cmd
::grammar::fa::op::reverse fa
::grammar::fa::op::complete fa ?sink?
::grammar::fa::op::remove_eps fa
::grammar::fa::op::trim fa ?what?
::grammar::fa::op::determinize fa ?mapvar?
::grammar::fa::op::minimize fa ?mapvar?
::grammar::fa::op::complement fa
::grammar::fa::op::kleene fa
::grammar::fa::op::optional fa
::grammar::fa::op::union fa fb ?mapvar?
::grammar::fa::op::intersect fa fb ?mapvar?
::grammar::fa::op::difference fa fb ?mapvar?
::grammar::fa::op::concatenate fa fb ?mapvar?
::grammar::fa::op::fromRegex fa regex ?over?
::grammar::fa::op::toRegexp fa
::grammar::fa::op::toRegexp2 fa
::grammar::fa::op::toTclRegexp regexp symdict
::grammar::fa::op::simplifyRegexp regexp

Description

This package provides a number of complex operations on finite -automatons (Short: FA), -as provided by the package grammar::fa. -The package does not provide the ability to create and/or manipulate -such FAs, nor the ability to execute a FA for a stream of symbols. -Use the packages grammar::fa -and grammar::fa::interpreter for that. -Another package related to this is grammar::fa::compiler -which turns a FA into an executor class which has the definition of -the FA hardwired into it.

For more information about what a finite automaton is see section -FINITE AUTOMATONS in package grammar::fa.

API

The package exports the API described here. All commands modify their -first argument. I.e. whatever FA they compute is stored back into -it. Some of the operations will construct an automaton whose states -are all new, but related to the states in the source -automaton(s). These operations take variable names as optional -arguments where they will store mappings which describe the -relationship(s). -The operations can be loosely partitioned into structural and language -operations. The latter are defined in terms of the language the -automaton(s) accept, whereas the former are defined in terms of the -structural properties of the involved automaton(s). Some operations -are both. -Structure operations

::grammar::fa::op::constructor cmd

This command has to be called by the user of the package before any other -operations is performed, to establish a command which can be used to -construct a FA container object. If this is not done several operations -will fail as they are unable to construct internal and transient containers -to hold state and/or partial results.

Any container class using this package for complex operations should set -its own class command as the constructor. See package grammar::fa -for an example.

::grammar::fa::op::reverse fa

Reverses the fa. This is done by reversing the direction of all -transitions and swapping the sets of start and final -states. The language of fa changes unpredictably.

::grammar::fa::op::complete fa ?sink?

Completes the fa complete, but nothing is done if the -fa is already complete. This implies that only the first -in a series of multiple consecutive complete operations on fa -will perform anything. The remainder will be null operations.

The language of fa is unchanged by this operation.

This is done by adding a single new state, the sink, and -transitions from all other states to that sink for all symbols they -have no transitions for. The sink itself is made complete by adding -loop transitions for all symbols.

The argument sink provides the name for the new state and most -not be present in the fa if specified. If the name is not -specified the command will name the state "sinkn", where n -is set so that there are no collisions with existing states.

Note that the sink state is not useful by definition. In -other words, while the FA becomes complete, it is also -not useful in the strict sense as it has a state from which -no final state can be reached.

::grammar::fa::op::remove_eps fa

Removes all epsilon-transitions from the fa in such a manner the -the language of fa is unchanged. However nothing is done if the -fa is already epsilon-free. -This implies that only the first in a series of multiple consecutive -complete operations on fa will perform anything. The remainder -will be null operations.

Note: This operation may cause states to become unreachable or -not useful. These states are not removed by this operation. -Use ::grammar::fa::op::trim for that instead.

::grammar::fa::op::trim fa ?what?

Removes unwanted baggage from fa. -The legal values for what are listed below. The command defaults -to !reachable|!useful if no specific argument was given.

!reachable: Removes all states which are not reachable from a start state.
!useful: Removes all states which are unable to reach a final state.
!reachable&!useful
!(reachable|useful): Removes all states which are not reachable from a start state and are -unable to reach a final state.
!reachable|!useful
!(reachable&useful): Removes all states which are not reachable from a start state or are -unable to reach a final state.

::grammar::fa::op::determinize fa ?mapvar?

Makes the fa deterministic without changing the language -accepted by the fa. However nothing is done if the fa is -already deterministic. This implies that only the first in a -series of multiple consecutive complete operations on fa will -perform anything. The remainder will be null operations.

The command will store a dictionary describing the relationship -between the new states of the resulting dfa and the states of the -input nfa in mapvar, if it has been specified. Keys of the -dictionary are the handles for the states of the resulting dfa, values -are sets of states from the input nfa.

Note: An empty dictionary signals that the command was able to -make the fa deterministic without performing a full subset -construction, just by removing states and shuffling transitions around -(As part of making the FA epsilon-free).

Note: The algorithm fails to make the FA deterministic in the -technical sense if the FA has no start state(s), because determinism -requires the FA to have exactly one start states. -In that situation we make a best effort; and the missing start state -will be the only condition preventing the generated result from being -deterministic. -It should also be noted that in this case the possibilities for -trimming states from the FA are also severely reduced as we cannot -declare states unreachable.

::grammar::fa::op::minimize fa ?mapvar?

Creates a FA which accepts the same language as fa, but has a -minimal number of states. Uses Brzozowski's method to accomplish this.

The command will store a dictionary describing the relationship -between the new states of the resulting minimal fa and the states of -the input fa in mapvar, if it has been specified. Keys of the -dictionary are the handles for the states of the resulting minimal fa, -values are sets of states from the input fa.

Note: An empty dictionary signals that the command was able to -minimize the fa without having to compute new states. This -should happen if and only if the input FA was already minimal.

Note: If the algorithm has no start or final states to work -with then the result might be technically minimal, but have a very -unexpected structure. -It should also be noted that in this case the possibilities for -trimming states from the FA are also severely reduced as we cannot -declare states unreachable.

Language operations -All operations in this section require that all input FAs have at -least one start and at least one final state. Otherwise the language of -the FAs will not be defined, making the operation senseless (as it -operates on the languages of the FAs in a defined manner).

::grammar::fa::op::complement fa

Complements fa. This is possible if and only if fa is -complete and deterministic. The resulting FA accepts the -complementary language of fa. In other words, all inputs not -accepted by the input are accepted by the result, and vice versa.

The result will have all states and transitions of the input, and -different final states.

::grammar::fa::op::kleene fa

Applies Kleene's closure to fa. -The resulting FA accepts all strings S for which we can find a -natural number n (0 inclusive) and strings A1 ... An -in the language of fa such that S is the concatenation of -A1 ... An. -In other words, the language of the result is the infinite union over -finite length concatenations over the language of fa.

The result will have all states and transitions of the input, and new -start and final states.

::grammar::fa::op::optional fa

Makes the fa optional. In other words it computes the FA which -accepts the language of fa and the empty the word (epsilon) as -well.

The result will have all states and transitions of the input, and new -start and final states.

::grammar::fa::op::union fa fb ?mapvar?

Combines the FAs fa and fb such that the resulting FA -accepts the union of the languages of the two FAs.

The result will have all states and transitions of the two input FAs, -and new start and final states. All states of fb which exist in -fa as well will be renamed, and the mapvar will contain a -mapping from the old states of fb to the new ones, if present.

It should be noted that the result will be non-deterministic, even if -the inputs are deterministic.

::grammar::fa::op::intersect fa fb ?mapvar?

Combines the FAs fa and fb such that the resulting FA -accepts the intersection of the languages of the two FAs. In other -words, the result will accept a word if and only if the word is -accepted by both fa and fb. The result will be useful, but -not necessarily deterministic or minimal.

The command will store a dictionary describing the relationship -between the new states of the resulting fa and the pairs of states of -the input FAs in mapvar, if it has been specified. Keys of the -dictionary are the handles for the states of the resulting fa, values -are pairs of states from the input FAs. Pairs are represented by -lists. The first element in each pair will be a state in fa, the -second element will be drawn from fb.

::grammar::fa::op::difference fa fb ?mapvar?

Combines the FAs fa and fb such that the resulting FA -accepts the difference of the languages of the two FAs. In other -words, the result will accept a word if and only if the word is -accepted by fa, but not by fb. This can also be expressed -as the intersection of fa with the complement of fb. The -result will be useful, but not necessarily deterministic or minimal.

::grammar::fa::op::concatenate fa fb ?mapvar?

Combines the FAs fa and fb such that the resulting FA -accepts the cross-product of the languages of the two FAs. I.e. a word -W will be accepted by the result if there are two words A and B -accepted by fa, and fb resp. and W is the concatenation of -A and B.

The result FA will be non-deterministic.

::grammar::fa::op::fromRegex fa regex ?over?

Generates a non-deterministic FA which accepts the same language as -the regular expression regex. If the over is specified it -is treated as the set of symbols the regular expression and the -automaton are defined over. The command will compute the set from the -"S" constructors in regex when over was not -specified. This set is important if and only if the complement -operator "!" is used in regex as the complementary language of -an FA is quite different for different sets of symbols.

The regular expression is represented by a nested list, which forms -a syntax tree. The following structures are legal:

{S x}

Atomic regular expression. Everything else is constructed from -these. Accepts the Symbol "x".

{. A1 A2 ...}

Concatenation operator. Accepts the concatenation of the regular -expressions A1, A2, etc.

Note that this operator accepts zero or more arguments. With zero -arguments the represented language is epsilon, the empty word.

{| A1 A2 ...}

Choice operator, also called "Alternative". Accepts all input accepted -by at least one of the regular expressions A1, A2, etc. In -other words, the union of A1, A2.

Note that this operator accepts zero or more arguments. With zero -arguments the represented language is the empty language, -the language without words.

{& A1 A2 ...}

Intersection operator, logical and. Accepts all input accepted which -is accepted by all of the regular expressions A1, A2, -etc. In other words, the intersection of A1, A2.

{? A}

Optionality operator. Accepts the empty word and anything from the -regular expression A.

{* A}

Kleene closure. Accepts the empty word and any finite concatenation of -words accepted by the regular expression A.

{+ A}

Positive Kleene closure. Accepts any finite concatenation of words -accepted by the regular expression A, but not the empty word.

{! A}

Complement operator. Accepts any word not accepted by the regular -expression A. Note that the complement depends on the set of -symbol the result should run over. See the discussion of the argument -over before.

::grammar::fa::op::toRegexp fa

This command generates and returns a regular expression which accepts -the same language as the finite automaton fa. The regular -expression is in the format as described above, for -::grammar::fa::op::fromRegex.

::grammar::fa::op::toRegexp2 fa

This command has the same functionality as ::grammar::fa::op::toRegexp, -but uses a different algorithm to simplify the generated regular expressions.

::grammar::fa::op::toTclRegexp regexp symdict

This command generates and returns a regular expression in Tcl syntax for the -regular expression regexp, if that is possible. regexp is in the -same format as expected by ::grammar::fa::op::fromRegex.

The command will fail and throw an error if regexp contains -complementation and intersection operations.

The argument symdict is a dictionary mapping symbol names to -pairs of syntactic type and Tcl-regexp. If a symbol -occurring in the regexp is not listed in this dictionary then -single-character symbols are considered to designate themselves -whereas multiple-character symbols are considered to be a character -class name.

::grammar::fa::op::simplifyRegexp regexp

This command simplifies a regular expression by applying the following -algorithm first to the main expression and then recursively to all -sub-expressions:

Convert the expression into a finite automaton.
Minimize the automaton.
Convert the automaton back to a regular expression.
Choose the shorter of original expression and expression from -the previous step.

EXAMPLES

Bugs, Ideas, Feedback

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

Keywords

automaton, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, state, transducer

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_me/gasm.html Index: embedded/www/tcllib/files/modules/grammar_me/gasm.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/gasm.html +++ /dev/null @@ -1,445 +0,0 @@ - -

- -

grammar::me::cpu::gasm(n) 0.1 tcllib "Grammar operations and usage"

Name

grammar::me::cpu::gasm - ME assembler

Table Of Contents
Synopsis
Description
DEFINITIONS
API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

- -

Description

This package provides a simple in-memory assembler. Its origin is that -of a support package for use by packages converting PEG and other -grammars into a corresponding matcher based on the ME virtual machine, -like page::compiler::peg::mecpu. Despite that it is actually -mostly agnostic regarding the instructions, users can choose any -instruction set they like.

The program under construction is held in a graph structure (See -package struct::graph) during assembly and subsequent -manipulation, with instructions represented by nodes, and the flow of -execution between instructions explicitly encoded in the arcs between -them.

In this model jumps are not encoded explicitly, they are implicit in -the arcs. The generation of explicit jumps is left to any code -converting the graph structure into a more conventional -representation. The same goes for branches. They are implicitly -encoded by all instructions which have two outgoing arcs, whereas all -other instructions have only one outgoing arc. Their conditonality is -handled by tagging their outgoing arcs with information about the -conditions under which they are taken.

While the graph the assembler operates on is supplied from the -outside, i.e. external, it does manage some internal state, namely:

The handle of the graph node most assembler operations will -work on, the anchor.
A mapping from arbitrary strings to instructions. I.e. it is -possible to label an instruction during assembly, and later -recall that instruction by its label.
The condition code to use when creating arcs between -instructions, which is one of always, ok, and -fail.
The current operation mode, one of halt, -okfail, and !okfail.
The name of a node in a tree. This, and the operation mode -above are the parts most heavily influenced by the needs of a grammar -compiler, as they assume some basic program structures (selected -through the operation mode), and intertwine the graph with a tree, -like the AST for the grammar to be compiled.

DEFINITIONS

As the graph the assembler is operating on, and the tree it is -intertwined with, are supplied to the assembler from the outside it is -necessary to specify the API expected from them, and to describe the -structures expected and/or generated by the assembler in either.

Any graph object command used by the assembler has to provide -the API as specified in the documentation for the package -struct::graph.
Any tree object command used by the assembler has to provide -the API as specified in the documentation for the package -struct::tree.
Any instruction (node) generated by the assembler in a graph -will have at least two, and at most three attributes:
-
-
instruction
-
The value of this attribute is the name of -the instruction. The only names currently defined by the assembler are -the three pseudo-instructions
-
-
NOP
-
This instruction does nothing. Useful for fixed -framework nodes, unchanging jump destinations, and the like. No -arguments.
-
C
-
A .NOP to allow the insertion of arbitrary comments -into the instruction stream, i.e. a comment node. One argument, the -text of the comment.
-
BRA
-
A .NOP serving as explicitly coded conditional -branch. No arguments.
-
-
However we reserve the space of all instructions whose names begin -with a "." (dot) for future use by the assembler.
-
arguments
-
The value of this attribute is a list of -strings, the arguments of the instruction. The contents are dependent -on the actual instruction and the assembler doesn't know or care about -them. This means for example that it has no builtin knowledge about -what instruction need which arguments and thus doesn't perform any -type of checking.
-
expr
-
This attribute is optional. When it is present its -value is the name of a node in the tree intertwined with the graph.
-
-
Any arc between two instructions will have one attribute:
-
-
condition
-
The value of this attribute determines under which -condition execution will take this arc. It is one of always, -ok, and fail. The first condition is used for all arcs -which are the single outgoing arc of an instruction. The other two are -used for the two outgoing arcs of an instruction which implicitly -encode a branch.
-
-
A tree node given to the assembler for cross-referencing will -be written to and given the following attributes, some fixed, some -dependent on the operation mode. All values will be references to -nodes in the instruction graph. Some of the instruction will expect -some or specific sets of these attributes.
-
-
gas::entry
-
Always written.
-
gas::exit
-
Written for all modes but okfail.
-
gas::exit::ok
-
Written for mode okfail.
-
gas::exit::fail
-
Written for mode okfail.
-
-

API

::grammar::me::cpu::gasm::begin g n ?mode? ?note?

This command starts the assembly of an instruction sequence, and -(re)initializes the state of the assembler. After completion of the -instruction sequence use ::grammar::me::cpu::gasm::done to -finalize the assembler.

It will operate on the graph g in the specified mode -(Default is okfail). As part of the initialization it will -always create a standard .NOP instruction and label it "entry". The -creation of the remaining standard instructions is -mode-dependent:

halt: An "icf_halt" instruction labeled "exit/return".
!okfail: An "icf_ntreturn" instruction labeled "exit/return".
okfail: Two .NOP instructions labeled "exit/ok" and -"exit/fail" respectively.

The note, if specified (default is not), is given to the "entry" .NOP instruction.

The node reference n is simply stored for use by -::grammar::me::cpu::gasm::done. It has to refer to a node in the -tree t argument of that command.

After the initialization is done the "entry" instruction will be the -anchor, and the condition code will be set to always.

The command returns the empy string as its result.

::grammar::me::cpu::gasm::done --> t

This command finalizes the creation of an instruction sequence and -then clears the state of the assembler. -NOTE that this does not delete any of the created -instructions. They can be made available to future begin/done cycles. -Further assembly will be possible only after reinitialization of the -system via ::grammar::me::cpu::gasm::begin.

Before the state is cleared selected references to selected -instructions will be written to attributes of the node n in the -tree t. -Which instructions are saved is mode-dependent. Both mode -and the destination node n were specified during invokation of -::grammar::me::cpu::gasm::begin.

Independent of the mode a reference to the instruction labeled "entry" -will be saved to the attribute gas::entry of n. The -reference to the node n will further be saved into the attribute -"expr" of the "entry" instruction. Beyond that

halt: A reference to the instruction labeled -"exit/return" will be saved to the attribute gas::exit of -n.
okfail: See halt.
!okfail: Reference to the two instructions labeled -"exit/ok" and "exit/fail" will be saved to the attributes -gas::exit::ok and gas::exit::fail of n -respectively.

The command returns the empy string as its result.

::grammar::me::cpu::gasm::state

This command returns the current state of the assembler. Its format is -not documented and considered to be internal to the package.

::grammar::me::cpu::gasm::state! s

This command takes a serialized assembler state s as returned by -::grammar::me::cpu::gasm::state and makes it the current state -of the assembler.

Note that this may overwrite label definitions, however all -non-conflicting label definitions in the state before are not touched -and merged with s.

The command returns the empty string as its result.

::grammar::me::cpu::gasm::lift t dst = src

This command operates on the tree t. It copies the contents of -the attributes gas::entry, gas::exit::ok and -gas::exit::fail from the node src to the node dst. -It returns the empty string as its result.

::grammar::me::cpu::gasm::Inline t node label

This command links an instruction sequence created by an earlier -begin/done pair into the current instruction sequence.

To this end it

reads the instruction references from the attributes -gas::entry, gas::exit::ok, and gas::exit::fail -from the node n of the tree t and makes them available to -assembler und the labels label/entry, label/exit::ok, and -label/exit::fail respectively.
Creates an arc from the anchor to the node labeled -label/entry, and tags it with the current condition code.
Makes the node labeled label/exit/ok the new anchor.

The command returns the empty string as its result.

::grammar::me::cpu::gasm::Cmd cmd ?arg...?

This is the basic command to add instructions to the graph. -It creates a new instruction of type cmd with the given -arguments arg... -If the anchor was defined it will also create an arc from the -anchor to the new instruction using the current condition code. -After the call the new instruction will be the anchor and the -current condition code will be set to always.

The command returns the empty string as its result.

::grammar::me::cpu::gasm::Bra

This is a convenience command to create a .BRA pseudo-instruction. It -uses ::grammar::me::cpu::gasm::Cmd to actually create the -instruction and inherits its behaviour.

::grammar::me::cpu::gasm::Nop text

This is a convenience command to create a .NOP pseudo-instruction. It -uses ::grammar::me::cpu::gasm::Cmd to actually create the -instruction and inherits its behaviour. -The text will be saved as the first and only argument of the new -instruction.

::grammar::me::cpu::gasm::Note text

This is a convenience command to create a .C pseudo-instruction, -i.e. a comment. It uses ::grammar::me::cpu::gasm::Cmd to -actually create the instruction and inherits its behaviour. -The text will be saved as the first and only argument of the new -instruction.

::grammar::me::cpu::gasm::Jmp label

This command creates an arc from the anchor to the instruction -labeled with label, and tags with the the current condition -code.

The command returns the empty string as its result.

::grammar::me::cpu::gasm::Exit

This command creates an arc from the anchor to one of the exit -instructions, based on the operation mode (see -::grammar::me::cpu::gasm::begin), and tags it with current -condition code.

For mode okfail it links to the instruction labeled either -"exit/ok" or "exit/fail", depending on the current condition code, and -tagging it with the current condition code -For the other two modes it links to the instruction labeled -"exit/return", tagging it condition code always, independent -the current condition code.

The command returns the empty string as its result.

::grammar::me::cpu::gasm::Who label

This command returns a reference to the instruction labeled with -label.

::grammar::me::cpu::gasm::/Label name

This command labels the anchor with name. -Note that an instruction can have more than one label.

The command returns the empty string as its result.

::grammar::me::cpu::gasm::/Clear

This command clears the anchor, leaving it undefined, and -further resets the current condition code to always.

The command returns the empty string as its result.

::grammar::me::cpu::gasm::/Ok

This command sets the current condition code to ok.

The command returns the empty string as its result.

::grammar::me::cpu::gasm::/Fail

This command sets the current condition code to fail.

The command returns the empty string as its result.

::grammar::me::cpu::gasm::/At name

This command sets the anchor to the instruction labeled with -name, and further resets the current condition code to -always.

The command returns the empty string as its result.

::grammar::me::cpu::gasm::/CloseLoop

This command marks the anchor as the last instruction in a loop -body, by creating the attribute LOOP.

The command returns the empty string as its result.

Bugs, Ideas, Feedback

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

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

Keywords

assembler, grammar, graph, parsing, tree, virtual machine

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_me/me_ast.html Index: embedded/www/tcllib/files/modules/grammar_me/me_ast.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_ast.html +++ /dev/null @@ -1,218 +0,0 @@ - -

- -

grammar::me_ast(n) 0.1 tcllib "Grammar operations and usage"

Name

grammar::me_ast - Various representations of ASTs

Table Of Contents
Description
AST VALUES
AST OBJECTS
EXTENDED AST OBJECTS
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Description

This document specifies various representations for the -abstract syntax trees (short AST) generated by -instances of ME virtual machines, independent of variant. -Please go and read the document grammar::me_intro first if -you do not know what a ME virtual machine is.

ASTs and all the representations we specify distinguish between two -types of nodes, namely:

Terminal: Terminal nodes refer to the terminal symbols found in the token -stream. They are always leaf nodes. I.e. terminal nodes never have -children.
Nonterminal: Nonterminal nodes represent a nonterminal symbol of the grammar used -during parsing. They can occur as leaf and inner nodes of the -tree.

Both types of nodes carry basic range information telling a user which -parts of the input are covered by the node by providing the location -of the first and last tokens found within the range. Locations are -provided as non-negative integer offsets from the beginning of the -token stream, with the first token found in the stream located at -offset 0 (zero).

The root of an AS tree can be either a terminal or nonterminal node.

AST VALUES

This representation of ASTs is a Tcl list. The main list represents -the root node of the tree, with the representations of the children -nested within.

Each node is represented by a single Tcl list containing three or more -elements. The first element is either the empty string or the name of -a nonterminal symbol (which is never the empty string). The second and -third elements are then the locations of the first and last tokens. -Any additional elements after the third are then the representations -of the children, with the leftmost child first, i.e. as the fourth -element of the list representing the node.

AST OBJECTS

In this representation an AST is represented by a Tcl object command -whose API is compatible to the tree objects provided by the package -struct::tree. I.e it has to support at least all of the -methods described by that package, and may support more.

Because of this the remainder of the specifications is written using -the terms of struct::tree.

Each node of the AST directly maps to a node in the tree object. All -data beyond the child nodes, i.e. node type and input locations, are -stored in attributes of the node in the tree object. They are:

type: The type of the AST node. The recognized values are terminal -and nonterminal.
range: The locations of the first and last token of the terminal data in the -input covered by the node. This is a list containing two locations.
detail: This attribute is present only for nonterminal nodes. It contains the -name of the nonterminal symbol stored in the node.

EXTENDED AST OBJECTS

Extended AST objects are like AST objects, with additional -information.

detail

This attribute is now present at all nodes. Its contents are unchanged -for nonterminal nodes. For terminal nodes it contains a list -describing all tokens from the input which are covered by the node.

Each element of the list contains the token name, the associated -lexeme attribute, line number, and column index, in this order.

range_lc

This new attribute is defined for all nodes, and contains the -locations from attribute range translated into line number and -column index. Lines are counted from 1, columns are counted from 0.

Bugs, Ideas, Feedback

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

Keywords

AST, abstract syntax tree

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_me/me_cpu.html Index: embedded/www/tcllib/files/modules/grammar_me/me_cpu.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_cpu.html +++ /dev/null @@ -1,357 +0,0 @@ - -

- -

grammar::me::cpu(n) 0.2 tcllib "Grammar operations and usage"

Name

grammar::me::cpu - Virtual machine implementation II for parsing token streams

Table Of Contents
Synopsis
Description
API -
- CLASS API
- OBJECT API
-
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require grammar::me::cpu ?0.2?

- -

Description

This package provides an implementation of the ME virtual machine. -Please go and read the document grammar::me_intro first if -you do not know what a ME virtual machine is.

This implementation provides an object-based API and the machines are -not truly tied to Tcl. A C implementation of the same API is quite -possible.

Internally the package actually uses the value-based machine -manipulation commands as provided by the package -grammar::me::cpu::core to perform its duties.

API

CLASS API

The package directly provides only a single command for the -construction of ME virtual machines.

::grammar::me::cpu meName matchcode

The command creates a new ME machine object with an associated global -Tcl command whose name is meName. This command may be used to -invoke various operations on the machine. -It has the following general form:

meName option ?arg arg ...?: Option and the args determine the exact behavior of the -command.

The argument matchcode contains the match instructions the -machine has to execute while parsing the input stream. Please read -section MATCH CODE REPRESENTATION of the -documentation for the package grammar::me::cpu::core for -the specification of the structure of this value.

The tokmap argument taken by the implementation provided by the -package grammar::me::tcl is here hidden inside of the match -instructions and therefore not needed.

OBJECT API

All ME virtual machine objects created by the class command specified -in section CLASS API support the methods listed below.

The machines provided by this package provide methods for operation in -both push- and pull-styles. Push-style means that tokens are pushed -into the machine state when they arrive, triggering further execution -until they are consumed. In other words, this allows the machine to be -suspended and resumed at will and an arbitrary number of times, the -quasi-parallel operation of several machines, and the operation as -part of the event loop.

meName lc location

This method converts the location of a token given as offset in the -input stream into the associated line number and column index. The -result of the command is a 2-element list containing the two values, -in the order mentioned in the previous sentence. -This allows higher levels to convert the location information found in -the error status and the generated AST into more human readable data.

Note that the command is not able to convert locations which -have not been reached by the machine yet. In other words, if the -machine has read 7 tokens the command is able to convert the offsets -0 to 6, but nothing beyond that. This also shows that -it is not possible to convert offsets which refer to locations before -the beginning of the stream.

meName tok ?from ?to??

This method returns a Tcl list containing the part of the input stream -between the locations from and to (both inclusive). If -to is not specified it will default to the value of from. -If from is not specified either the whole input stream is returned.

Each element of the returned list is a list of four elements, the -token, its associated lexeme, line number, and column index, in this -order. -This command places the same restrictions on its location arguments as -the method lc.

meName pc state

This method takes the state value of a ME virtual machine and returns -the current value of the stored program counter.

meName iseof state

This method takes the state value of a ME virtual machine and returns -the current value of the stored eof flag.

meName at state

This method takes the state value of a ME virtual machine and returns -the current location in the input stream.

meName cc state

This method takes the state value of a ME virtual machine and returns -the current token.

meName sv

This command returns the current semantic value SV stored in -the machine. This is an abstract syntax tree as specified in the -document grammar::me_ast, section AST VALUES.

meName ok

This method returns the current match status OK.

meName error

This method returns the current error status ER.

meName lstk state

This method takes the state value of a ME virtual machine and returns -the location stack.

meName astk state

This method takes the state value of a ME virtual machine and returns -the AST stack.

meName mstk state

This method takes the state value of a ME virtual machine and returns -the AST marker stack.

meName estk state

This method takes the state value of a ME virtual machine and returns -the error stack.

meName rstk state

This method takes the state value of a ME virtual machine and returns -the subroutine return stack.

meName nc state

This method takes the state value of a ME virtual machine and returns -the nonterminal match cache as a dictionary.

meName ast

This method returns the current top entry of the AST stack AS. -This is an abstract syntax tree as specified in the document -grammar::me_ast, section AST VALUES.

meName halted

This method returns a boolean value telling the caller whether the -engine has halted execution or not. Halt means that no further -matching is possible, and the information retrieved via the other -method is final. Attempts to run the engine will be ignored, -until a reset is made.

meName code

This method returns the code information used to construct the -object. In other words, the match program executed by the machine.

meName eof

This method adds an end of file marker to the end of the input stream. -This signals the machine that the current contents of the input queue -are the final parts of the input and nothing will come after. Attempts -to put more characters into the queue will fail.

meName put tok lex line col

This method adds the token tok to the end of the input stream, -with associated lexeme data lex and line/column -information.

meName putstring string lvar cvar

This method adds each individual character in the string as a -token to the end of the input stream, from first to last. The lexemes -will be empty and the line/col information is computed based on the -characters encountered and the data in the variables lvar and -cvar.

meName run ?n?

This methods causes the engine to execute match instructions until -either

n instructions have been executed, or
a halt instruction was executed, or
the input queue is empty and the code is asking for more tokens to -process.

If no limit n was set only the last two conditions are checked -for.

meName pull nextcmd

This method implements pull-style operation of the machine. It causes -it to execute match instructions until either a halt instruction is -reached, or the command prefix -nextcmd ceases to deliver more tokens.

The command prefix nextcmd represents the input stream of -characters and is invoked by the machine whenever the a new character -from the stream is required. The instruction for handling this is -ict_advance. -The callback has to return either the empty list, or a list of 4 -elements containing the token, its lexeme attribute, and its location -as line number and column index, in this order. -The empty list is the signal that the end of the input stream has been -reached. The lexeme attribute is stored in the terminal cache, but -otherwise not used by the machine.

The end of the input stream for this method does not imply that method -eof is called for the machine as a whole. By avoiding this -and still asking for an explicit call of the method it is possible to -mix push- and pull-style operation during the lifetime of the machine.

meName reset

This method resets the machine to its initial state, discarding any -state it may have.

meName destroy

This method deletes the object and releases all resurces it claimed.

Bugs, Ideas, Feedback

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

Keywords

grammar, parsing, virtual machine

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_me/me_cpucore.html Index: embedded/www/tcllib/files/modules/grammar_me/me_cpucore.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_cpucore.html +++ /dev/null @@ -1,422 +0,0 @@ - -

- -

grammar::me::cpu::core(n) 0.2 tcllib "Grammar operations and usage"

Name

grammar::me::cpu::core - ME virtual machine state manipulation

Table Of Contents
Synopsis
Description
API -
- MATCH PROGRAM REPRESENTATION
-
CPU STATE
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require grammar::me::cpu::core ?0.2?

::grammar::me::cpu::core disasm asm
::grammar::me::cpu::core asm asm
::grammar::me::cpu::core new asm
::grammar::me::cpu::core lc state location
::grammar::me::cpu::core tok state ?from ?to??
::grammar::me::cpu::core pc state
::grammar::me::cpu::core iseof state
::grammar::me::cpu::core at state
::grammar::me::cpu::core cc state
::grammar::me::cpu::core sv state
::grammar::me::cpu::core ok state
::grammar::me::cpu::core error state
::grammar::me::cpu::core lstk state
::grammar::me::cpu::core astk state
::grammar::me::cpu::core mstk state
::grammar::me::cpu::core estk state
::grammar::me::cpu::core rstk state
::grammar::me::cpu::core nc state
::grammar::me::cpu::core ast state
::grammar::me::cpu::core halted state
::grammar::me::cpu::core code state
::grammar::me::cpu::core eof statevar
::grammar::me::cpu::core put statevar tok lex line col
::grammar::me::cpu::core run statevar ?n?

Description

This package provides an implementation of the ME virtual machine. -Please go and read the document grammar::me_intro first if -you do not know what a ME virtual machine is.

This implementation represents each ME virtual machine as a Tcl value -and provides commands to manipulate and query such values to show the -effects of executing instructions, adding tokens, retrieving state, -etc.

The values fully follow the paradigm of Tcl that every value is a -string and while also allowing C implementations for a proper -Tcl_ObjType to keep all the important data in native data structures. -Because of the latter it is recommended to access the state values -only through the commands of this package to ensure that -internal representation is not shimmered away.

The actual structure used by all state values is described in section -CPU STATE.

API

The package directly provides only a single command, and all the -functionality is made available through its methods.

::grammar::me::cpu::core disasm asm

This method returns a list containing a disassembly of the match -instructions in asm. The format of asm is specified in the -section MATCH PROGRAM REPRESENTATION.

Each element of the result contains instruction label, instruction -name, and the instruction arguments, in this order. The label can be -the empty string. Jump destinations are shown as labels, strings and -tokens unencoded. Token names are prefixed with their numeric id, if, -and only if a tokmap is defined. The two components are separated by a -colon.

::grammar::me::cpu::core asm asm

This method returns code in the format as specified in section -MATCH PROGRAM REPRESENTATION generated from ME assembly -code asm, which is in the format as returned by the method -disasm.

::grammar::me::cpu::core new asm

This method creates state value for a ME virtual machine in its -initial state and returns it as its result.

The argument matchcode contains a Tcl representation of the -match instructions the machine has to execute while parsing the input -stream. Its format is specified in the section -MATCH PROGRAM REPRESENTATION.

The tokmap argument taken by the implementation provided by the -package grammar::me::tcl is here hidden inside of the match -instructions and therefore not needed.

::grammar::me::cpu::core lc state location

This method takes the state value of a ME virtual machine and uses it -to convert a location in the input stream (as offset) into a line -number and column index. The result of the method is a 2-element list -containing the two pieces in the order mentioned in the previous -sentence.

Note that the method cannot convert locations which the machine -has not yet read from the input stream. In other words, if the machine -has read 7 characters so far it is possible to convert the offsets -0 to 6, but nothing beyond that. This also shows that -it is not possible to convert offsets which refer to locations before -the beginning of the stream.

This utility allows higher levels to convert the location offsets -found in the error status and the AST into more human readable data.

::grammar::me::cpu::core tok state ?from ?to??

This method takes the state value of a ME virtual machine and returns -a Tcl list containing the part of the input stream between the -locations from and to (both inclusive). If to is not -specified it will default to the value of from. If from is -not specified either the whole input stream is returned.

This method places the same restrictions on its location arguments as -the method lc.

::grammar::me::cpu::core pc state

This method takes the state value of a ME virtual machine and returns -the current value of the stored program counter.

::grammar::me::cpu::core iseof state

This method takes the state value of a ME virtual machine and returns -the current value of the stored eof flag.

::grammar::me::cpu::core at state

This method takes the state value of a ME virtual machine and returns -the current location in the input stream.

::grammar::me::cpu::core cc state

This method takes the state value of a ME virtual machine and returns -the current token.

::grammar::me::cpu::core sv state

This method takes the state value of a ME virtual machine and returns -the current semantic value stored in it. -This is an abstract syntax tree as specified in the document -grammar::me_ast, section AST VALUES.

::grammar::me::cpu::core ok state

This method takes the state value of a ME virtual machine and returns -the match status stored in it.

::grammar::me::cpu::core error state

This method takes the state value of a ME virtual machine and returns -the current error status stored in it.

::grammar::me::cpu::core lstk state

This method takes the state value of a ME virtual machine and returns -the location stack.

::grammar::me::cpu::core astk state

This method takes the state value of a ME virtual machine and returns -the AST stack.

::grammar::me::cpu::core mstk state

This method takes the state value of a ME virtual machine and returns -the AST marker stack.

::grammar::me::cpu::core estk state

This method takes the state value of a ME virtual machine and returns -the error stack.

::grammar::me::cpu::core rstk state

This method takes the state value of a ME virtual machine and returns -the subroutine return stack.

::grammar::me::cpu::core nc state

This method takes the state value of a ME virtual machine and returns -the nonterminal match cache as a dictionary.

::grammar::me::cpu::core ast state

This method takes the state value of a ME virtual machine and returns -the abstract syntax tree currently at the top of the AST stack stored -in it. -This is an abstract syntax tree as specified in the document -grammar::me_ast, section AST VALUES.

::grammar::me::cpu::core halted state

This method takes the state value of a ME virtual machine and returns -the current halt status stored in it, i.e. if the machine has stopped -or not.

::grammar::me::cpu::core code state

This method takes the state value of a ME virtual machine and returns -the code stored in it, i.e. the instructions executed by the machine.

::grammar::me::cpu::core eof statevar

This method takes the state value of a ME virtual machine as stored in -the variable named by statevar and modifies it so that the eof -flag inside is set. This signals to the machine that whatever token -are in the input queue are the last to be processed. There will be no -more.

::grammar::me::cpu::core put statevar tok lex line col

This method takes the state value of a ME virtual machine as stored in -the variable named by statevar and modifies it so that the token -tok is added to the end of the input queue, with associated -lexeme data lex and line/column information.

The operation will fail with an error if the eof flag of the machine -has been set through the method eof.

::grammar::me::cpu::core run statevar ?n?

This method takes the state value of a ME virtual machine as stored in -the variable named by statevar, executes a number of -instructions and stores the state resulting from their modifications -back into the variable.

The execution loop will run until either

n instructions have been executed, or
a halt instruction was executed, or
the input queue is empty and the code is asking for more tokens to -process.

If no limit n was set only the last two conditions are checked -for.

MATCH PROGRAM REPRESENTATION

A match program is represented by nested Tcl list. The first element, -asm, is a list of integer numbers, the instructions to execute, -and their arguments. The second element, pool, is a list of -strings, referenced by the instructions, for error messages, token -names, etc. The third element, tokmap, provides ordering -information for the tokens, mapping their names to their numerical -rank. This element can be empty, forcing lexicographic comparison when -matching ranges.

All ME instructions are encoded as integer numbers, with the mapping -given below. A number of the instructions, those which handle error -messages, have been given an additional argument to supply that -message explicitly instead of having it constructed from token names, -etc. This allows the machine state to store only the message ids -instead of the full strings.

Jump destination arguments are absolute indices into the asm -element, refering to the instruction to jump to. Any string arguments -are absolute indices into the pool element. Tokens, characters, -messages, and token (actually character) classes to match are coded as -references into the pool as well.

"ict_advance message"
"ict_match_token tok message"
"ict_match_tokrange tokbegin tokend message"
"ict_match_tokclass code message"
"inc_restore branchlabel nt"
"inc_save nt"
"icf_ntcall branchlabel"
"icf_ntreturn"
"iok_ok"
"iok_fail"
"iok_negate"
"icf_jalways branchlabel"
"icf_jok branchlabel"
"icf_jfail branchlabel"
"icf_halt"
"icl_push"
"icl_rewind"
"icl_pop"
"ier_push"
"ier_clear"
"ier_nonterminal message"
"ier_merge"
"isv_clear"
"isv_terminal"
"isv_nonterminal_leaf nt"
"isv_nonterminal_range nt"
"isv_nonterminal_reduce nt"
"ias_push"
"ias_mark"
"ias_mrewind"
"ias_mpop"

CPU STATE

A state value is a list containing the following elements, in the order listed below:

code: Match instructions, see MATCH PROGRAM REPRESENTATION.
pc: Program counter, int.
halt: Halt flag, boolean.
eof: Eof flag, boolean
tc: Terminal cache, and input queue. Structure see below.
cl: Current location, int.
ct: Current token, string.
ok: Match status, boolean.
sv: Semantic value, list.
er: Error status, list.
ls: Location stack, list.
as: AST stack, list.
ms: AST marker stack, list.
es: Error stack, list.
rs: Return stack, list.
nc: Nonterminal cache, dictionary.

tc, the input queue of tokens waiting for processing and the -terminal cache containing the tokens already processing are one -unified data structure simply holding all tokens and their -information, with the current location separating that which has been -processed from that which is waiting. -Each element of the queue/cache is a list containing the token, its -lexeme information, line number, and column index, in this order.

All stacks have their top element aat the end, i.e. pushing an item is -equivalent to appending to the list representing the stack, and -popping it removes the last element.

er, the error status is either empty or a list of two elements, -a location in the input, and a list of messages, encoded as references -into the pool element of the code.

nc, the nonterminal cache is keyed by nonterminal name and -location, each value a four-element list containing current location, -match status, semantic value, and error status, in this order.

Bugs, Ideas, Feedback

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

Keywords

grammar, parsing, virtual machine

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_me/me_intro.html Index: embedded/www/tcllib/files/modules/grammar_me/me_intro.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_intro.html +++ /dev/null @@ -1,179 +0,0 @@ - -

- -

grammar::me_intro(n) 0.1 tcllib "Grammar operations and usage"

Name

grammar::me_intro - Introduction to virtual machines for parsing token streams

Table Of Contents
Description
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Description

This document is an introduction to and overview of the basic -facilities for the parsing and/or matching of token -streams. One possibility often used for the token domain are -characters.

The packages themselves all provide variants of one -virtual machine, called a match engine (short -ME), which has all the facilities needed for the matching and -parsing of a stream, and which are either controlled directly, or are -customized with a match program. The virtual machine is basically a -pushdown automaton, with additional elements for backtracking and/or -handling of semantic data and construction of abstract syntax trees -(AST).

Because of the high degree of similarity in the actual implementations -of the aforementioned virtual machine and the data structures they -receive and generate these common parts are specified in a separate -document which will be referenced by the documentation for packages -actually implementing it.

The relevant documents are:

grammar::me_vm: Virtual machine specification.
grammar::me_ast: Specification of various representations used for abstract syntax -trees.
grammar::me::util: Utility commands.
grammar::me::tcl: Singleton ME virtual machine implementation tied to Tcl for control -flow and stacks. Hardwired for pull operation. Uninteruptible during -processing.
grammar::me::cpu: Object-based ME virtual machine implementation with explicit control -flow, and stacks, using bytecodes. Suspend/Resumable. Push/pull -operation.
grammar::me::cpu::core: Core functionality for state manipulation and stepping used in the -bytecode based implementation of ME virtual machines.

Bugs, Ideas, Feedback

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

Keywords

CFG, CFL, LL(k), PEG, TPDL, context-free grammar, context-free languages, expression, grammar, matching, parsing, parsing expression grammar, push down automaton, recursive descent, top-down parsing languages, transducer, virtual machine

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_me/me_tcl.html Index: embedded/www/tcllib/files/modules/grammar_me/me_tcl.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_tcl.html +++ /dev/null @@ -1,402 +0,0 @@ - -

- -

grammar::me::tcl(n) 0.1 tcllib "Grammar operations and usage"

Name

grammar::me::tcl - Virtual machine implementation I for parsing token streams

Table Of Contents
Synopsis
Description
API
MACHINE STATE
MACHINE INSTRUCTIONS
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require grammar::me::tcl ?0.1?

::grammar::me::tcl cmd ...
::grammar::me::tcl init nextcmd ?tokmap?
::grammar::me::tcl lc location
::grammar::me::tcl tok from ?to?
::grammar::me::tcl tokens
::grammar::me::tcl sv
::grammar::me::tcl ast
::grammar::me::tcl astall
::grammar::me::tcl ctok
::grammar::me::tcl nc
::grammar::me::tcl next
::grammar::me::tcl ord
::grammar::me::tcl::ict_advance message
::grammar::me::tcl::ict_match_token tok message
::grammar::me::tcl::ict_match_tokrange tokbegin tokend message
::grammar::me::tcl::ict_match_tokclass code message
::grammar::me::tcl::inc_restore nt
::grammar::me::tcl::inc_save nt startlocation
::grammar::me::tcl::iok_ok
::grammar::me::tcl::iok_fail
::grammar::me::tcl::iok_negate
::grammar::me::tcl::icl_get
::grammar::me::tcl::icl_rewind oldlocation
::grammar::me::tcl::ier_get
::grammar::me::tcl::ier_clear
::grammar::me::tcl::ier_nonterminal message location
::grammar::me::tcl::ier_merge olderror
::grammar::me::tcl::isv_clear
::grammar::me::tcl::isv_terminal
::grammar::me::tcl::isv_nonterminal_leaf nt startlocation
::grammar::me::tcl::isv_nonterminal_range nt startlocation
::grammar::me::tcl::isv_nonterminal_reduce nt startlocation ?marker?
::grammar::me::tcl::ias_push
::grammar::me::tcl::ias_mark
::grammar::me::tcl::ias_pop2mark marker

Description

This package provides an implementation of the ME virtual machine. -Please go and read the document grammar::me_intro first if -you do not know what a ME virtual machine is.

This implementation is tied very strongly to Tcl. All the stacks in -the machine state are handled through the Tcl stack, all control flow -is handled by Tcl commands, and the remaining machine instructions are -directly mapped to Tcl commands. Especially the matching of -nonterminal symbols is handled by Tcl procedures as well, essentially -extending the machine implementation with custom instructions.

Further on the implementation handles only a single machine which is -uninteruptible during execution and hardwired for pull operation. I.e. -it explicitly requests each new token through a callback, pulling them -into its state.

A related package is grammar::peg::interp which provides a -generic interpreter / parser for parsing expression grammars (PEGs), -implemented on top of this implementation of the ME virtual machine.

API

The commands documented in this section do not implement any of the -instructions of the ME virtual machine. They provide the facilities -for the initialization of the machine and the retrieval of important -information.

::grammar::me::tcl cmd ...

This is an ensemble command providing access to the commands listed in -this section. See the methods themselves for detailed specifications.

::grammar::me::tcl init nextcmd ?tokmap?

This command (re)initializes the machine. It returns the empty -string. This command has to be invoked before any other command of -this package.

The optional dictionary tokmap maps from tokens to integer -numbers. If present the numbers impose an order on the tokens, which -is subsequently used by ict_match_tokrange to determine if a -token is in the specified range or not. If no token map is specified -the lexicographic order of th token names will be used instead. This -choice is especially asensible when using characters as tokens.

::grammar::me::tcl lc location

This command converts the location of a token given as offset in the -input stream into the associated line number and column index. The -result of the command is a 2-element list containing the two values, -in the order mentioned in the previous sentence. -This allows higher levels to convert the location information found in -the error status and the generated AST into more human readable data.

After a call of init the state used for the conversion is -cleared, making further conversions impossible until the machine has -read tokens again.

::grammar::me::tcl tok from ?to?

This command returns a Tcl list containing the part of the input -stream between the locations from and to (both -inclusive). If to is not specified it will default to the value -of from.

Each element of the returned list is a list of four elements, the -token, its associated lexeme, line number, and column index, in this -order. -In other words, each element has the same structure as the result of -the nextcmd callback given to ::grammar::me::tcl::init

This command places the same restrictions on its location arguments as -::grammar::me::tcl::lc.

::grammar::me::tcl tokens

This command returns the number of tokens currently known to the ME -virtual machine.

::grammar::me::tcl sv

This command returns the current semantic value SV stored in -the machine. This is an abstract syntax tree as specified in the -document grammar::me_ast, section AST VALUES.

::grammar::me::tcl ast

This method returns the abstract syntax tree currently at the top of -the AST stack of the ME virtual machine. This is an abstract syntax -tree as specified in the document grammar::me_ast, section -AST VALUES.

::grammar::me::tcl astall

This method returns the whole stack of abstract syntax trees currently -known to the ME virtual machine. Each element of the returned list is -an abstract syntax tree as specified in the document -grammar::me_ast, section AST VALUES. -The top of the stack resides at the end of the list.

::grammar::me::tcl ctok

This method returns the current token considered by the ME virtual -machine.

::grammar::me::tcl nc

This method returns the contents of the nonterminal cache as a -dictionary mapping from "symbol,location" to match -information.

::grammar::me::tcl next

This method returns the next token callback as specified during -initialization of the ME virtual machine.

::grammar::me::tcl ord

This method returns a dictionary containing the tokmap specified -during initialization of the ME virtual machine. -::grammar::me::tcl::ok -This variable contains the current match status OK. It is -provided as variable instead of a command because that makes access to -this information faster, and the speed of access is considered very -important here as this information is used constantly to determine the -control flow.

MACHINE STATE

Please go and read the document grammar::me_vm first for a -specification of the basic ME virtual machine and its state.

This implementation manages the state described in that document, -except for the stacks minus the AST stack. In other words, location -stack, error stack, return stack, and ast marker stack are implicitly -managed through standard Tcl scoping, i.e. Tcl variables in -procedures, outside of this implementation.

MACHINE INSTRUCTIONS

Please go and read the document grammar::me_vm first for a -specification of the basic ME virtual machine and its instruction set.

This implementation maps all instructions to Tcl commands in the -namespace "::grammar::me::tcl", except for the stack related commands, -nonterminal symbols and control flow. -Here we simply list the commands and explain the differences to the -specified instructions, if there are any. For their semantics see the -aforementioned specification. The machine commands are not -reachable through the ensemble command ::grammar::me::tcl.

::grammar::me::tcl::ict_advance message: No changes.
::grammar::me::tcl::ict_match_token tok message: No changes.
::grammar::me::tcl::ict_match_tokrange tokbegin tokend message: If, and only if a token map was specified during initialization then -the arguments are the numeric representations of the smallest and -largest tokens in the range. Otherwise they are the relevant tokens -themselves and lexicographic comparison is used.
::grammar::me::tcl::ict_match_tokclass code message: No changes.
::grammar::me::tcl::inc_restore nt: Instead of taking a branchlabel the command returns a boolean value. -The result will be true if and only if cached information was -found. The caller has to perform the appropriate branching.
::grammar::me::tcl::inc_save nt startlocation: The command takes the start location as additional argument, as it is -managed on the Tcl stack, and not in the machine state.
icf_ntcall branchlabel
icf_ntreturn: These two instructions are not mapped to commands. They are control -flow instructions and handled in Tcl.
::grammar::me::tcl::iok_ok: No changes.
::grammar::me::tcl::iok_fail: No changes.
::grammar::me::tcl::iok_negate: No changes.
icf_jalways branchlabel
icf_jok branchlabel
icf_jfail branchlabel
icf_halt: These four instructions are not mapped to commands. They are control -flow instructions and handled in Tcl.
::grammar::me::tcl::icl_get: This command returns the current location CL in the input. -It replaces icl_push.
::grammar::me::tcl::icl_rewind oldlocation: The command takes the location as argument as it comes from the -Tcl stack, not the machine state.
icl_pop: Not mapped, the stacks are not managed by the package.
::grammar::me::tcl::ier_get: This command returns the current error state ER. -It replaces ier_push.
::grammar::me::tcl::ier_clear: No changes.
::grammar::me::tcl::ier_nonterminal message location: The command takes the location as argument as it comes from the -Tcl stack, not the machine state.
::grammar::me::tcl::ier_merge olderror: The command takes the second error state to merge as argument as it -comes from the Tcl stack, not the machine state.
::grammar::me::tcl::isv_clear: No changes.
::grammar::me::tcl::isv_terminal: No changes.
::grammar::me::tcl::isv_nonterminal_leaf nt startlocation: The command takes the start location as argument as it comes from the -Tcl stack, not the machine state.
::grammar::me::tcl::isv_nonterminal_range nt startlocation: The command takes the start location as argument as it comes from the -Tcl stack, not the machine state.
::grammar::me::tcl::isv_nonterminal_reduce nt startlocation ?marker?: The command takes start location and marker as argument as it comes -from the Tcl stack, not the machine state.
::grammar::me::tcl::ias_push: No changes.
::grammar::me::tcl::ias_mark: This command returns a marker for the current state of the AST stack -AS. The marker stack is not managed by the machine.
::grammar::me::tcl::ias_pop2mark marker: The command takes the marker as argument as it comes from the -Tcl stack, not the machine state. It replaces ias_mpop.

Bugs, Ideas, Feedback

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

Keywords

grammar, parsing, virtual machine

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_me/me_util.html Index: embedded/www/tcllib/files/modules/grammar_me/me_util.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_util.html +++ /dev/null @@ -1,199 +0,0 @@ - -

- -

grammar::me::util(n) 0.1 tcllib "Grammar operations and usage"

Name

grammar::me::util - AST utilities

Table Of Contents
Synopsis
Description
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require grammar::me::util ?0.1?

::grammar::me::util::ast2tree ast tree ?root?
::grammar::me::util::ast2etree ast mcmd tree ?root?
mcmd lc location
mcmd tok from ?to?
::grammar::me::util::tree2ast tree ?root?

Description

This package provides a number of utility command for the conversion -between the various representations of abstract syntax trees as -specified in the document grammar::me_ast.

::grammar::me::util::ast2tree ast tree ?root?

This command converts an ast from value to object -representation. All nodes in the ast will be converted into -nodes of this tree, with the root of the AST a child of the node -root. If this node is not explicitly specified the root of the -tree is used. Existing content of tree is not touched, i.e. neither -removed nor changed, with the exception of the specified root node, -which will gain a new child.

::grammar::me::util::ast2etree ast mcmd tree ?root?

This command is like ::grammar::me::util::ast2tree, except that -the result is in the extended object representation of the input AST. -The source of the extended information is the command prefix -mcmd. -It has to understand two methods, lc, and tok, with -the semantics specified below.

mcmd lc location

Takes the location of a token given as offset in the input stream and -return a 2-element list containing the associated line number and -column index, in this order.

mcmd tok from ?to?

Takes one or two locations from and to as offset in the -input stream and returns a Tcl list containing the specified part of -the input stream. Both location are inclusive. If to is not -specified it will default to the value of from.

Each element of the returned list is a list containing the token, its -associated lexeme, the line number, and column index, in this order.

Both the ensemble command ::grammar::me::tcl provided by the -package grammar::me::tcl and the objects command created by -the package ::grammar::me::cpu fit the above specification.

::grammar::me::util::tree2ast tree ?root?

This command converts an ast in (extended) object representation -into a value and returns it. -If a root node is specified the AST is generated from that node -downward. Otherwise the root of the tree object is used as the -starting point.

Bugs, Ideas, Feedback

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

Keywords

abstract syntax tree, syntax tree, tree

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_me/me_vm.html Index: embedded/www/tcllib/files/modules/grammar_me/me_vm.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_vm.html +++ /dev/null @@ -1,549 +0,0 @@ - -

- -

grammar::me_vm(n) 0.1 tcllib "Grammar operations and usage"

Name

grammar::me_vm - Virtual machine for parsing token streams

Table Of Contents
Description
MACHINE STATE
MACHINE INSTRUCTIONS -
- TERMINAL MATCHING
- NONTERMINAL MATCHING
- UNCONDITIONAL MATCHING
- CONTROL FLOW
- INPUT LOCATION HANDLING
- ERROR HANDLING
- SEMANTIC VALUES
- AST STACK HANDLING
-
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Description

Please go and read the document grammar::me_intro first for -an overview of the various documents and their relations.

This document specifies a virtual machine for the controlled matching -and parsing of token streams, creating an -abstract syntax tree (short AST) reflecting the -structure of the input. Special machine features are the caching and -reuse of partial results, caching of the encountered input, and the -ability to backtrack in both input and AST creation.

These features make the specified virtual machine especially useful to -packrat parsers based on parsing expression grammars. It is however -not restricted to this type of parser. Normal LL and LR parsers can be -implemented with it as well.

The following sections will discuss first the abstract state kept by -ME virtual machines, and then their instruction set.

MACHINE STATE

A ME virtual machine manages the following state:

Current token CT

The token from the input under consideration by the machine.

This information is used and modified by the instructions defined in -the section -TERMINAL MATCHING.

Current location CL

The location of the current token in the input stream, as -offset relative to the beginning of the stream. The first token is -considered to be at offset 0.

This information is implicitly used and modified by the instructions -defined in the sections -TERMINAL MATCHING and -NONTERMINAL MATCHING, -and can be directly queried and modified by the instructions defined -in section -INPUT LOCATION HANDLING.

Location stack LS

In addition to the above a stack of locations, for backtracking. -Locations can put on the stack, removed from it, and removed with -setting the current location.

Match status OK

A boolean value, the result of the last attempt at matching input. -It is set to true if that attempt was successful, and -false otherwise.

This information is influenced by the instructions defined in the -sections -TERMINAL MATCHING, -NONTERMINAL MATCHING, and -UNCONDITIONAL MATCHING. -It is queried by the instructions defined in the section -CONTROL FLOW.

Semantic value SV

The semantic value associated with (generated by) the last attempt at -matching input. Contains either the empty string or a node for the -abstract syntax tree constructed from the input.

This information is influenced by the instructions defined in the -sections -SEMANTIC VALUES, and -AST STACK HANDLING.

AST stack AS

A stack of partial abstract syntax trees constructed by the machine -during matching.

This information is influenced by the instructions defined in the -sections -SEMANTIC VALUES, and -AST STACK HANDLING.

AST Marker stack MS

In addition to the above a stack of stacks, for backtracking. This is -actually a stack of markers into the AST stack, thus implicitly -snapshooting the state of the AST stack at some point in time. Markers -can be put on the stack, dropped from it, and used to roll back the -AST stack to an earlier state.

This information is influenced by the instructions defined in the -sections -SEMANTIC VALUES, and -AST STACK HANDLING.

Error status ER

Error information associated with the last attempt at matching -input. Contains either the empty string or a list of 2 elements, a -location in the input and a list of error messages associated with -it, in this order.

Note that error information can be set even if the last attempt -at matching input was successful. For example the *-operator (matching -a sub-expression zero or more times) in a parsing expression grammar -is always successful, even if it encounters a problem further in the -input and has to backtrack. Such problems must not be forgotten when -continuing to match.

This information is queried and influenced by the instructions defined -in the sections -TERMINAL MATCHING, -NONTERMINAL MATCHING, and -ERROR HANDLING.

Error stack ES

In addition to the above a stack of error information, to allow the -merging of current and older error information when performing -backtracking in choices after an unsucessful match.

This information is queried and influenced by the instructions defined -in the sections -TERMINAL MATCHING, -NONTERMINAL MATCHING, and -ERROR HANDLING.

Return stack RS

A stack of program counter values, i.e. locations in the code -controlling the virtual machine, for the management of subroutine -calls, i.e. the matching of nonterminal symbols.

This information is queried and influenced by the instructions defined -in the section -NONTERMINAL MATCHING.

Nonterminal cache NC

A cache of machine states (A 4-tuple containing a location in the -input, match status OK, semantic value SV, and error -status ER) keyed by name of nonterminal symbol and location in -the input stream.

The key location is where machine started the attempt to match the -named nonterminal symbol, and the location in the value is where -machine ended up after the attempt completed, independent of the -success of the attempt.

This status is queried and influenced by the instructions defined in -the section -NONTERMINAL MATCHING.

MACHINE INSTRUCTIONS

With the machine state specified it is now possible to explain the -instruction set of ME virtual machines. They are grouped roughly by -the machine state they influence and/or query.

TERMINAL MATCHING

First the instructions to match tokens from the input stream, and -by extension all terminal symbols.

These instructions are the only ones which may retrieve a new token -from the input stream. This is a may and not a will -because the instructions will a retrieve new token if, and only if the -current location CL is at the head of the stream. -If the machine has backtracked (see icl_rewind) the instructions -will retrieve the token to compare against from the internal cache.

ict_advance message

This instruction tries to advance to the next token in the input -stream, i.e. the one after the current location CL. The -instruction will fail if, and only if the end of the input stream is -reached, i.e. if there is no next token.

The sucess/failure of the instruction is remembered in the match -status OK. In the case of failure the error status ER is -set to the current location and the message message. -In the case of success the error status ER is cleared, the new -token is made the current token CT, and the new location is -made the current location CL.

The argument message is a reference to the string to put into -the error status ER, if such is needed.

ict_match_token tok message

This instruction tests the current token CT for equality -with the argument tok and records the result in the match -status OK. The instruction fails if the current token is -not equal to tok.

In case of failure the error status ER is set to the current -location CL and the message message, and the -current location CL is moved one token backwards. -Otherwise, i.e. upon success, the error status ER is cleared -and the current location CL is not touched.

ict_match_tokrange tokbegin tokend message

This instruction tests the current token CT for being in -the range of tokens from tokbegin to tokend -(inclusive) and records the result in the match status OK. The -instruction fails if the current token is not inside the range.

In case of failure the error status ER is set to the current -location CL and the message message, and the current location -CL is moved one token backwards. -Otherwise, i.e. upon success, the error status ER is cleared -and the current location CL is not touched.

ict_match_tokclass code message

This instruction tests the current token CT for being a member -of the token class code and records the result in the match -status OK. The instruction fails if the current token is not a -member of the specified class.

Currently the following classes are legal:

alnum: A token is accepted if it is a unicode alphabetical character, or a digit.
alpha: A token is accepted if it is a unicode alphabetical character.
digit: A token is accepted if it is a unicode digit character.
xdigit: A token is accepted if it is a hexadecimal digit character.
punct: A token is accepted if it is a unicode punctuation character.
space: A token is accepted if it is a unicode space character.

NONTERMINAL MATCHING

The instructions in this section handle the matching of nonterminal -symbols. They query the nonterminal cache NC for saved -information, and put such information into the cache.

The usage of the cache is a performance aid for backtracking parsers, -allowing them to avoid an expensive rematch of complex nonterminal -symbols if they have been encountered before.

inc_restore branchlabel nt

This instruction checks if the nonterminal cache NC contains -information about the nonterminal symbol nt, at the current -location CL. If that is the case the instruction will update -the machine state (current location CL, match status OK, -semantic value SV, and error status ER) with the found -information and continue execution at the instruction refered to by -the branchlabel. The new current location CL will be the -last token matched by the nonterminal symbol, i.e. belonging to it.

If no information was found the instruction will continue execution at -the next instruction.

Together with icf_ntcall it is possible to generate code for -memoized and non-memoized matching of nonterminal symbols, either as -subroutine calls, or inlined in the caller.

inc_save nt

This instruction saves the current state of the machine (current -location CL, match status OK, semantic value SV, -and error status ER), to the nonterminal cache NC. It -will also pop an entry from the location stack LS and save it -as the start location of the match.

It is expected to be called at the end of matching a nonterminal -symbol, with nt the name of the nonterminal symbol the code was -working on. This allows the instruction inc_restore to check for -and retrieve the data, should we have to match this nonterminal symbol -at the same location again, during backtracking.

icf_ntcall branchlabel

This instruction invokes the code for matching the nonterminal symbol -nt as a subroutine. To this end it stores the current program -counter PC on the return stack RS, the current location -CL on the location stack LS, and then continues -execution at the address branchlabel.

The next matching icf_ntreturn will cause the execution to -continue at the instruction coming after the call.

icf_ntreturn

This instruction will pop an entry from the return stack RS, -assign it to the program counter PC, and then continue -execution at the new address.

UNCONDITIONAL MATCHING

The instructions in this section are the remaining match -operators. They change the match status OK directly and -unconditionally.

iok_ok: This instruction sets the match status OK to true, -indicating a successful match.
iok_fail: This instruction sets the match status OK to false, -indicating a failed match.
iok_negate: This instruction negates the match status OK, turning a failure -into a success and vice versa.

CONTROL FLOW

The instructions in this section implement both conditional and -unconditional control flow. The conditional jumps query the match -status OK.

icf_jalways branchlabel: This instruction sets the program counter PC to the address -specified by branchlabel and then continues execution from -there. This is an unconditional jump.
icf_jok branchlabel: This instruction sets the program counter PC to the address -specified by branchlabel. This happens if, and only if the match -status OK indicates a success. Otherwise it simply continues -execution at the next instruction. This is a conditional jump.
icf_jfail branchlabel: This instruction sets the program counter PC to the address -specified by branchlabel. This happens if, and only if the match -status OK indicates a failure. Otherwise it simply continues -execution at the next instruction. This is a conditional jump.
icf_halt: This instruction halts the machine and blocks any further execution.

INPUT LOCATION HANDLING

The instructions in this section are for backtracking, they manipulate -the current location CL of the machine state. -They allow a user of the machine to query and save locations in the -input, and to rewind the current location CL to saved -locations, making them one of the components enabling the -implementation of backtracking parsers.

icl_push: This instruction pushes a copy of the current location CL on -the location stack LS.
icl_rewind: This instruction pops an entry from the location stack LS and -then moves the current location CL back to this point in the -input.
icl_pop: This instruction pops an entry from the location stack LS and -discards it.

ERROR HANDLING

The instructions in this section provide read and write access to the -error status ER of the machine.

ier_push

This instruction pushes a copy of the current error status ER -on the error stack ES.

ier_clear

This instruction clears the error status ER.

ier_nonterminal message

This instruction checks if the error status ER contains an -error whose location is just past the location found in the top entry -of the location stack LS. -Nothing happens if no such error is found. -Otherwise the found error is replaced by an error at the location -found on the stack, having the message message.

ier_merge

This instruction pops an entry from the error stack ES, merges -it with the current error status ER and stores the result of -the merge as the new error status ER.

The merge is performed as described below:

If one of the two error states is empty the other is chosen. If -neither error state is empty, and refering to different locations, -then the error state with the location further in the input is -chosen. If both error states refer to the same location their messages -are merged (with removing duplicates).

SEMANTIC VALUES

The instructions in this section manipulate the semantic value -SV.

isv_clear

This instruction clears the semantic value SV.

isv_terminal

This instruction creates a terminal AST node for the current token -CT, makes it the semantic value SV, and also pushes the -node on the AST stack AS.

isv_nonterminal_leaf nt

This instruction creates a nonterminal AST node without any children -for the nonterminal nt, and makes it the semantic value -SV.

This instruction should be executed if, and only if the match status -OK indicates a success. -In the case of a failure isv_clear should be called.

isv_nonterminal_range nt

This instruction creates a nonterminal AST node for the nonterminal -nt, with a single terminal node as its child, and makes this AST -the semantic value SV. The terminal node refers to the input -string from the location found on top of the location stack LS -to the current location CL (both inclusive).

This instruction should be executed if, and only if the match status -OK indicates a success. -In the case of a failure isv_clear should be called.

isv_nonterminal_reduce nt

This instruction creates a nonterminal AST node for the nonterminal -nt and makes it the semantic value SV.

All entries on the AST stack AS above the marker found in the -top entry of the AST Marker stack MS become children of the new -node, with the entry at the stack top becoming the rightmost child. If -the AST Marker stack MS is empty the whole stack is used. The -AST marker stack MS is left unchanged.

This instruction should be executed if, and only if the match status -OK indicates a success. -In the case of a failure isv_clear should be called.

AST STACK HANDLING

The instructions in this section manipulate the AST stack AS, -and the AST Marker stack MS.

ias_push: This instruction pushes the semantic value SV on the AST stack -AS.
ias_mark: This instruction pushes a marker for the current state of the AST -stack AS on the AST Marker stack MS.
ias_mrewind: This instruction pops an entry from the AST Marker stack MS and -then proceeds to pop entries from the AST stack AS until the -state represented by the popped marker has been reached again. -Nothing is done if the AST stack AS is already smaller than -indicated by the popped marker.
ias_mpop: This instruction pops an entry from the AST Marker stack MS and -discards it.

Bugs, Ideas, Feedback

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

Keywords

grammar, parsing, virtual machine

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_peg/peg.html Index: embedded/www/tcllib/files/modules/grammar_peg/peg.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_peg/peg.html +++ /dev/null @@ -1,592 +0,0 @@ - -

- -

grammar::peg(n) 0.1 tcllib "Grammar operations and usage"

Name

grammar::peg - Create and manipulate parsing expression grammars

Table Of Contents
Synopsis
Description -
-
PARSING EXPRESSION GRAMMARS
REFERENCES
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require snit
package require grammar::peg ?0.1?

::grammar::peg pegName ?=|:=|<--|as|deserialize src?
pegName destroy
pegName clear
pegName = srcPEG
pegName --> dstPEG
pegName serialize
pegName deserialize serialization
pegName is valid
pegName start ?pe?
pegName nonterminals
pegName nonterminal add nt pe
pegName nonterminal delete nt1 ?nt2 ...?
pegName nonterminal exists nt
pegName nonterminal rename nt ntnew
pegName nonterminal mode nt ?mode?
pegName nonterminal rule nt
pegName unknown nonterminals

Description

This package provides a container class for -parsing expression grammars (Short: PEG). -It allows the incremental definition of the grammar, its manipulation -and querying of the definition. -The package neither provides complex operations on the grammar, nor has -it the ability to execute a grammar definition for a stream of symbols. -Two packages related to this one are grammar::mengine and -grammar::peg::interpreter. The first of them defines a -general virtual machine for the matching of a character stream, and -the second implements an interpreter for parsing expression grammars -on top of that virtual machine.

TERMS & CONCEPTS

PEGs are similar to context-free grammars, but not equivalent; in some -cases PEGs are strictly more powerful than context-free grammars (there -exist PEGs for some non-context-free languages). -The formal mathematical definition of parsing expressions and parsing -expression grammars can be found in section -PARSING EXPRESSION GRAMMARS.

In short, we have terminal symbols, which are the most basic -building blocks for sentences, and nonterminal symbols -with associated parsing expressions, defining the grammatical -structure of the sentences. The two sets of symbols are distinctive, -and do not overlap. When speaking about symbols the word "symbol" is -often left out. The union of the sets of terminal and nonterminal -symbols is called the set of symbols.

Here the set of terminal symbols is not explicitly managed, -but implicitly defined as the set of all characters. Note that this -means that we inherit from Tcl the ability to handle all of Unicode.

A pair of nonterminal and parsing expression is also -called a grammatical rule, or rule for short. In the -context of a rule the nonterminal is often called the left-hand-side -(LHS), and the parsing expression the right-hand-side (RHS).

The start expression of a grammar is a parsing expression -from which all the sentences contained in the language specified by -the grammar are derived. -To make the understanding of this term easier let us assume for a -moment that the RHS of each rule, and the start expression, is either -a sequence of symbols, or a series of alternate parsing expressions. -In the latter case the rule can be seen as a set of rules, each -providing one alternative for the nonterminal. -A parsing expression A' is now a derivation of a parsing expression A -if we pick one of the nonterminals N in the expression, and one of the -alternative rules R for N, and then replace the nonterminal in A with -the RHS of the chosen rule. Here we can see why the terminal symbols -are called such. They cannot be expanded any further, thus terminate -the process of deriving new expressions. -An example

-    Rules
-      (1)  A <- a B c
-      (2a) B <- d B
-      (2b) B <- e
-    Some derivations, using starting expression A.
-      A -/1/-> a B c -/2a/-> a d B c -/2b/-> a d e c
-

A derived expression containing only terminal symbols is a -sentence. The set of all sentences which can be derived from -the start expression is the language of the grammar.

Some definitions for nonterminals and expressions:

A nonterminal A is called reachable if it is possible to derive -a parsing expression from the start expression which contains A.
A nonterminal A is called useful if it is possible to derive a -sentence from it.
A nonterminal A is called recursive if it is possible to derive -a parsing expression from it which contains A, again.
The FIRST set of a nonterminal A contains all the symbols which -can occur of as the leftmost symbol in a parsing expression derived from -A. If the FIRST set contains A itself then that nonterminal is called -left-recursive.
The LAST set of a nonterminal A contains all the symbols which -can occur of as the rightmost symbol in a parsing expression derived from -A. If the LAST set contains A itself then that nonterminal is called -right-recursive.
The FOLLOW set of a nonterminal A contains all the symbols which -can occur after A in a parsing expression derived from the start -expression.
A nonterminal (or parsing expression) is called nullable if the -empty sentence can be derived from it.

And based on the above definitions for grammars:

A grammar G is recursive if and only if it contains a nonterminal -A which is recursive. The terms left- and right-recursive, -and useful are analogously defined.
A grammar is minimal if it contains only reachable and -useful nonterminals.
A grammar is wellformed if it is not left-recursive. Such -grammars are also complete, which means that they always succeed -or fail on all input sentences. For an incomplete grammar on the -other hand input sentences exist for which an attempt to match them -against the grammar will not terminate.
As we wish to allow ourselves to build a grammar incrementally in a -container object we will encounter stages where the RHS of one or more -rules reference symbols which are not yet known to the container. Such -a grammar we call invalid. -We cannot use the term incomplete as this term is already -taken, see the last item.

CONTAINER CLASS API

The package exports the API described here.

::grammar::peg pegName ?=|:=|<--|as|deserialize src?

The command creates a new container object for a parsing expression -grammar and returns the fully qualified name of the object command as -its result. The API the returned command is following is described in -the section CONTAINER OBJECT API. It may be used to invoke -various operations on the container and the grammar within.

The new container, i.e. grammar will be empty if no src is -specified. Otherwise it will contain a copy of the grammar contained -in the src. -The src has to be a container object reference for all operators -except deserialize. -The deserialize operator requires src to be the -serialization of a parsing expression grammar instead.

An empty grammar has no nonterminal symbols, and the start expression -is the empty expression, i.e. epsilon. It is valid, but not -useful.

CONTAINER OBJECT API

All grammar container objects provide the following methods for the -manipulation of their contents:

pegName destroy

Destroys the grammar, including its storage space and associated -command.

pegName clear

Clears out the definition of the grammar contained in pegName, -but does not destroy the object.

pegName = srcPEG

Assigns the contents of the grammar contained in srcPEG to -pegName, overwriting any existing definition. -This is the assignment operator for grammars. It copies the grammar -contained in the grammar object srcPEG over the grammar -definition in pegName. The old contents of pegName are -deleted by this operation.

This operation is in effect equivalent to

-    pegName deserialize [srcPEG serialize]
-

pegName --> dstPEG

This is the reverse assignment operator for grammars. It copies the -automation contained in the object pegName over the grammar -definition in the object dstPEG. -The old contents of dstPEG are deleted by this operation.

This operation is in effect equivalent to

-    dstPEG deserialize [pegName serialize]
-

pegName serialize

This method serializes the grammar stored in pegName. In other -words it returns a tcl value completely describing that -grammar. -This allows, for example, the transfer of grammars over arbitrary -channels, persistence, etc. -This method is also the basis for both the copy constructor and the -assignment operator.

The result of this method has to be semantically identical over all -implementations of the grammar::peg interface. This is what -will enable us to copy grammars between different implementations of -the same interface.

The result is a list of four elements with the following structure:

The constant string grammar::peg.
A dictionary. Its keys are the names of all known nonterminal symbols, -and their associated values are the parsing expressions describing -their sentennial structure.
A dictionary. Its keys are the names of all known nonterminal symbols, -and their associated values hints to a matcher regarding the semantic -values produced by the symbol.
The last item is a parsing expression, the start expression -of the grammar.

Assuming the following PEG for simple mathematical expressions

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

a possible serialization is

-    grammar::peg \\
-    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\
-     Factor     {x Term {* {x AddOp Term}}} \\
-     Term       Number \\
-     MulOp      {/ * /} \\
-     AddOp      {/ + -} \\
-     Number     {x {? Sign} {+ Digit}} \\
-     Sign       {/ + -} \\
-     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \\
-    } \\
-    {Expression value     Factor     value \\
-     Term       value     MulOp      value \\
-     AddOp      value     Number     value \\
-     Sign       value     Digit      value \\
-    }
-    Expression
-

A possible one, because the order of the nonterminals in the -dictionary is not relevant.

pegName deserialize serialization

This is the complement to serialize. It replaces the grammar -definition in pegName with the grammar described by the -serialization value. The old contents of pegName are -deleted by this operation.

pegName is valid

A predicate. It tests whether the PEG in pegName is valid. -See section TERMS & CONCEPTS for the definition of this -grammar property. -The result is a boolean value. It will be set to true if -the PEG has the tested property, and false otherwise.

pegName start ?pe?

This method defines the start expression of the grammar. It -replaces the previously defined start expression with the parsing -expression pe. -The method fails and throws an error if pe does not contain a -valid parsing expression as specified in the section -PARSING EXPRESSIONS. In that case the existing start -expression is not changed. -The method returns the empty string as its result.

If the method is called without an argument it will return the currently -defined start expression.

pegName nonterminals

Returns the set of all nonterminal symbols known to the grammar.

pegName nonterminal add nt pe

This method adds the nonterminal nt and its associated parsing -expression pe to the set of nonterminal symbols and rules of the -PEG contained in the object pegName. -The method fails and throws an error if either the string nt is -already known as a symbol of the grammar, or if pe does not -contain a valid parsing expression as specified in the section -PARSING EXPRESSIONS. In that case the current set of -nonterminal symbols and rules is not changed. -The method returns the empty string as its result.

pegName nonterminal delete nt1 ?nt2 ...?

This method removes the named symbols nt1, nt2 from the -set of nonterminal symbols of the PEG contained in the object -pegName. -The method fails and throws an error if any of the strings is not -known as a nonterminal symbol. In that case the current set of -nonterminal symbols is not changed. -The method returns the empty string as its result.

The stored grammar becomes invalid if the deleted nonterminals are -referenced by the RHS of still-known rules.

pegName nonterminal exists nt

A predicate. It tests whether the nonterminal symbol nt is known -to the PEG in pegName. -The result is a boolean value. It will be set to true if the -symbol nt is known, and false otherwise.

pegName nonterminal rename nt ntnew

This method renames the nonterminal symbol nt to ntnew. -The method fails and throws an error if either nt is not known -as a nonterminal, or if ntnew is a known symbol. -The method returns the empty string as its result.

pegName nonterminal mode nt ?mode?

This mode returns or sets the semantic mode associated with the -nonterminal symbol nt. If no mode is specified the -current mode of the nonterminal is returned. Otherwise the current -mode is set to mode. -The method fails and throws an error if nt is not known as a -nonterminal. -The grammar interpreter implemented by the package -grammar::peg::interpreter recognizes the -following modes:

value: The semantic value of the nonterminal is the abstract syntax tree -created from the AST's of the RHS and a node for the nonterminal -itself.
match: The semantic value of the nonterminal is an the abstract syntax tree -consisting of single a node for the string matched by the RHS. The ASTs -generated by the RHS are discarded.
leaf: The semantic value of the nonterminal is an the abstract syntax tree -consisting of single a node for the nonterminal itself. The ASTs -generated by the RHS are discarded.
discard: The nonterminal has no semantic value. The ASTs generated by the RHS -are discarded (as well).

pegName nonterminal rule nt

This method returns the parsing expression associated with the -nonterminal nt. -The method fails and throws an error if nt is not known as a -nonterminal.

pegName unknown nonterminals

This method returns a list containing the names of all nonterminal -symbols which are referenced on the RHS of a grammatical rule, but -have no rule definining their structure. In other words, a list of -the nonterminal symbols which make the grammar invalid. The grammar -is valid if this list is empty.

PARSING EXPRESSIONS

Various methods of PEG container objects expect a parsing expression -as their argument, or will return such. This section specifies the -format such parsing expressions are in.

The string epsilon is an atomic parsing expression. It matches -the empty string.
The string alnum is an atomic parsing expression. It matches -any alphanumeric character.
The string alpha is an atomic parsing expression. It matches -any alphabetical character.
The string dot is an atomic parsing expression. It matches -any character.
The expression - [list t x] -is an atomic parsing expression. It matches the terminal string x.
The expression - [list n A] -is an atomic parsing expression. It matches the nonterminal A.
For parsing expressions e1, e2, ... the result of - [list / e1 e2 ... ] -is a parsing expression as well. -This is the ordered choice, aka prioritized choice.
For parsing expressions e1, e2, ... the result of - [list x e1 e2 ... ] -is a parsing expression as well. -This is the sequence.
For a parsing expression e the result of - [list * e] -is a parsing expression as well. -This is the kleene closure, describing zero or more -repetitions.
For a parsing expression e the result of - [list + e] -is a parsing expression as well. -This is the positive kleene closure, describing one or more -repetitions.
For a parsing expression e the result of - [list & e] -is a parsing expression as well. -This is the and lookahead predicate.
For a parsing expression e the result of - [list ! e] -is a parsing expression as well. -This is the not lookahead predicate.
For a parsing expression e the result of - [list ? e] -is a parsing expression as well. -This is the optional input.

Examples of parsing expressions where already shown, in the -description of the method serialize.

PARSING EXPRESSION GRAMMARS

For the mathematically inclined, a PEG is a 4-tuple (VN,VT,R,eS) where

VN is a set of nonterminal symbols,
VT is a set of terminal symbols,
R is a finite set of rules, where each rule is a pair (A,e), A in VN, -and e a parsing expression.
eS is a parsing expression, the start expression.

Further constraints are

The intersection of VN and VT is empty.
For all A in VT exists exactly one pair (A,e) in R. In other words, R -is a function from nonterminal symbols to parsing expressions.

Parsing expression are inductively defined via

The empty string (epsilon) is a parsing expression.
A terminal symbol a is a parsing expression.
A nonterminal symbol A is a parsing expression.
e1e2 is a parsing expression for parsing expressions -e1 and 2. This is called sequence.
e1/e2 is a parsing expression for parsing expressions -e1 and 2. This is called ordered choice.
e* is a parsing expression for parsing expression -e. This is called zero-or-more repetitions, also known -as kleene closure.
e+ is a parsing expression for parsing expression -e. This is called one-or-more repetitions, also known -as positive kleene closure.
!e is a parsing expression for parsing expression -e1. This is called a not lookahead predicate.
&e is a parsing expression for parsing expression -e1. This is called an and lookahead predicate.

PEGs are used to define a grammatical structure for streams of symbols -over VT. They are a modern phrasing of older formalisms invented by -Alexander Birham. These formalisms were called TS (TMG recognition -scheme), and gTS (generalized TS). Later they were renamed to TPDL -(Top-Down Parsing Languages) and gTPDL (generalized TPDL).

They can be easily implemented by recursive descent parsers with -backtracking. This makes them relatives of LL(k) Context-Free -Grammars.

REFERENCES

The Packrat Parsing and Parsing Expression Grammars Page, -by Bryan Ford, Massachusetts Institute of Technology. This is the main -entry page to PEGs, and their realization through Packrat Parsers.
Parsing Techniques - A Practical Guide , an online book -offering a clear, accessible, and thorough discussion of many -different parsing techniques with their interrelations and -applicabilities, including error recovery techniques.
Compilers and Compiler Generators, an online book using -CoCo/R, a generator for recursive descent parsers.

Bugs, Ideas, Feedback

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

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

Keywords

LL(k), TDPL, context-free languages, expression, grammar, parsing, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/grammar_peg/peg_interp.html Index: embedded/www/tcllib/files/modules/grammar_peg/peg_interp.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_peg/peg_interp.html +++ /dev/null @@ -1,212 +0,0 @@ - -

- -

grammar::peg::interp(n) 0.1.1 tcllib "Grammar operations and usage"

Name

grammar::peg::interp - Interpreter for parsing expression grammars

Table Of Contents
Synopsis
Description
THE INTERPRETER API
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

package require Tcl 8.4
package require grammar::mengine ?0.1?
package require grammar::peg::interp ?0.1.1?

::grammar::peg::interp::setup peg
::grammar::peg::interp::parse nextcmd errorvar astvar

Description

This package provides commands for the controlled matching of a -character stream via a parsing expression grammar and the creation -of an abstract syntax tree for the stream and partials.

It is built on top of the virtual machine provided by the package -grammar::me::tcl and directly interprets the parsing -expression grammar given to it. -In other words, the grammar is not pre-compiled but used as is.

The grammar to be interpreted is taken from a container object -following the interface specified by the package -grammar::peg::container. Only the relevant parts -are copied into the state of this package.

It should be noted that the package provides exactly one instance -of the interpreter, and interpreting a second grammar requires -the user to either abort or complete a running interpretation, or -to put them into different Tcl interpreters.

Also of note is that the implementation assumes a pull-type -handling of the input. In other words, the interpreter pulls -characters from the input stream as it needs them. For usage -in a push environment, i.e. where the environment pushes new -characters as they come we have to put the engine into its -own thread.

THE INTERPRETER API

The package exports the following API

::grammar::peg::interp::setup peg

This command (re)initializes the interpreter. It returns the -empty string. This command has to be invoked first, before any -matching run.

Its argument peg is the handle of an object containing the -parsing expression grammar to interpret. This grammar has to be -valid, or an error will be thrown.

::grammar::peg::interp::parse nextcmd errorvar astvar

This command interprets the loaded grammar and tries to match it -against the stream of characters represented by the command prefix -nextcmd.

The command prefix nextcmd represents the input stream of -characters and is invoked by the interpreter whenever the a new -character from the stream is required. -The callback has to return either the empty list, or a list of 4 -elements containing the token, its lexeme attribute, and its location -as line number and column index, in this order. -The empty list is the signal that the end of the input stream has been -reached. The lexeme attribute is stored in the terminal cache, but -otherwise not used by the machine.

The result of the command is a boolean value indicating whether the -matching process was successful (true), or not -(false). In the case of a match failure error information will -be stored into the variable referenced by errorvar. The variable -referenced by astvar will always contain the generated abstract -syntax tree, however in the case of an error it will be only partial -and possibly malformed.

The abstract syntax tree is represented by a nested list, as -described in section AST VALUES of -document grammar::me_ast.

Bugs, Ideas, Feedback

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

Keywords

LL(k), TDPL, context-free languages, expression, grammar, matching, parsing, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer, virtual machine

Category

Grammars and finite automata

Copyright

DELETED embedded/www/tcllib/files/modules/hook/hook.html Index: embedded/www/tcllib/files/modules/hook/hook.html ================================================================== --- embedded/www/tcllib/files/modules/hook/hook.html +++ /dev/null @@ -1,415 +0,0 @@ - -

- -

hook(n) 0.1 tcllib "Hooks"

Name

hook - Hooks

Table Of Contents
Synopsis
Description
Concepts -
- Introduction
- Bindings
- Subjects and observers
-
Reference
Example
Credits
Bugs, Ideas, Feedback
See Also
Keywords
Category
Copyright

Synopsis

package require Tcl 8.5
package require hook ?0.1?

hook bind ?subject? ?hook? ?observer? ?cmdPrefix?
hook call subject hook ?args...?
hook forget object
hook cget option
hook configure option value ...

Description

This package provides the hook ensemble command, which -implements the Subject/Observer pattern. It allows subjects, -which may be modules, objects, widgets, and so -forth, to synchronously call hooks which may be bound to an -arbitrary number of subscribers, called observers. A subject -may call any number of distinct hooks, and any number of observers can -bind callbacks to a particular hook called by a particular -subject. Hook bindings can be queried and deleted.

This man page is intended to be a reference only.

Concepts

Introduction

Tcl modules usually send notifications to other modules in two ways: -via Tk events, and via callback options like the text widget's --yscrollcommand option. Tk events are available only in Tk, -and callback options require tight coupling between the modules -sending and receiving the notification.

Loose coupling between sender and receiver is often desirable, -however. In Model/View/Controller terms, a View can send a command -(stemming from user input) to the Controller, which updates the -Model. The Model can then call a hook to which all relevant -Views subscribe. The Model is decoupled from the Views, and indeed -need not know whether any Views actually exist. -At present, Tcl/Tk has no standard mechanism for implementing loose -coupling of this kind. This package defines a new command, hook, -which implements just such a mechanism.

Bindings

The hook command manages a collection of hook bindings. A hook -binding has four elements:

A subject: the name of the entity that will be calling the -hook.
The hook itself. A hook usually reflects some occurrence in the -life of the subject that other entities might care to know -about. A hook has a name, and may also have arguments. Hook -names are arbitrary strings. Each subject must document the -names and arguments of the hooks it can call.
The name of the observer that wishes to receive the hook -from the subject.
A command prefix to which the hook arguments will be appended -when the binding is executed.

Subjects and observers

For convenience, this document collectively refers to subjects and -observers as objects, while placing no requirements on how -these objects are actually implemented. An object can be a -TclOO or Snit or XOTcl object, a Tcl -command, a namespace, a module, a pseudo-object managed by some other -object (as tags are managed by the Tk text widget) or simply a -well-known name.

Subject and observer names are arbitrary strings; however, as -hook might be used at the package level, it's necessary to have -conventions that avoid name collisions between packages written by -different people.

Therefore, any subject or observer name used in core or package level -code should look like a Tcl command name, and should be defined in a -namespace owned by the package. Consider, for example, an ensemble -command ::foo that creates a set of pseudo-objects and uses -hook to send notifications. The pseudo-objects have names -that are not commands and exist in their own namespace, rather like -file handles do. To avoid name collisions with subjects defined by -other packages, users of hook, these ::foo handles -should have names like ::foo::1, ::foo::2, and so on.

Because object names are arbitrary strings, application code can use -whatever additional conventions are dictated by the needs of the -application.

Reference

Hook provides the following commands:

hook bind ?subject? ?hook? ?observer? ?cmdPrefix?

This subcommand is used to create, update, delete, and query hook -bindings.

Called with no arguments it returns a list of the subjects with -hooks to which observers are currently bound.

Called with one argument, a subject, it returns a list of -the subject's hooks to which observers are currently bound.

Called with two arguments, a subject and a hook, it -returns a list of the observers which are currently bound to this -subject and hook.

Called with three arguments, a subject, a hook, and -an observer, it returns the binding proper, the command prefix -to be called when the hook is called, or the empty string if there is -no such binding.

Called with four arguments, it creates, updates, or deletes a -binding. If cmdPrefix is the empty string, it deletes any -existing binding for the subject, hook, and -observer; nothing is returned. Otherwise, cmdPrefix must -be a command prefix taking as many additional arguments as are -documented for the subject and hook. The binding is added -or updated, and the observer is returned.

If the observer is the empty string, "", it will create a -new binding using an automatically generated observer name of the form -::hook::ob<number>. The automatically generated name -will be returned, and can be used to query, update, and delete the -binding as usual. If automated observer names are always used, the -observer name effectively becomes a unique binding ID.

It is possible to call hook bind to create or delete a -binding to a subject and hook while in an observer binding -for that same subject and hook. The following rules -determine what happens when

-    hook bind $s $h $o $binding
-

is called during the execution of

-    hook call $s $h
-

No binding is ever called after it is deleted.
When a binding is called, the most recently given command prefix is -always used.
The set of observers whose bindings are to be called is determined -when this method begins to execute, and does not change thereafter, -except that deleted bindings are not called.

In particular:

If $os binding to $s and $h is deleted, and -$os binding has not yet been called during this execution of
-
```
-    hook call $s $h
-
```
-
it will not be called. (Note that it might already have been called; -and in all likelihood, it is probably deleting itself.)
If $o changes the command prefix that's bound to $s and -$h, and if $os binding has not yet been called during -this execution of
-
```
-    hook call $s $h
-
```
-
the new binding will be called when the time comes. (But again, it is -probably $os binding that is is making the change.)
If a new observer is bound to $s and $h, its binding will -not be called until the next invocation of
-
```
-    hook call $s $h
-
```
-

hook call subject hook ?args...?

This command is called when the named subject wishes to call the -named hook. All relevant bindings are called with the specified -arguments in the global namespace. Note that the bindings are called -synchronously, before the command returns; this allows the args -to include references to entities that will be cleaned up as soon as -the hook has been called.

The order in which the bindings are called is not guaranteed. If -sequence among observers must be preserved, define one observer and -have its bindings call the other callbacks directly in the proper -sequence.

Because the hook mechanism is intended to support loose -coupling, it is presumed that the subject has no knowledge of -the observers, nor any expectation regarding return values. This has a -number of implications:

hook call returns the empty string.
Normal return values from observer bindings are ignored.
Errors and other exceptional returns propagate normally by -default. This will rarely be what is wanted, because the subjects -usually have no knowledge of the observers and will therefore have no -particular competence at handling their errors. That makes it an -application issue, and so applications will usually want to define an --errorcommand.

If the -errorcommand configuration option has a non-empty -value, its value will be invoked for all errors and other exceptional -returns in observer bindings. See hook configure, below, for -more information on configuration options.

hook forget object

This command deletes any existing bindings in which the named -object appears as either the subject or the -observer. -Bindings deleted by this method will never be called again. In -particular,

If an observer is forgotten during a call to hook call, any -uncalled binding it might have had to the relevant subject and hook -will not be called subsequently.
If a subject $s is forgotten during a call to
-
```
hook call $s $h
```
-
then hook call will return as soon as the current binding -returns. No further bindings will be called.

hook cget option

This command returns the value of one of the hook command's -configuration options.

hook configure option value ...

This command sets the value of one or more of the hook command's -configuration options:

-errorcommand cmdPrefix

If the value of this option is the empty string, "", then errors -and other exception returns in binding scripts are propagated -normally. Otherwise, it must be a command prefix taking three -additional arguments:

a 4-element list {subject hook arglist observer},
the result string, and
the return options dictionary.

Given this information, the -errorcommand can choose to log -the error, call interp bgerror, delete the errant binding -(thus preventing the error from arising a second time) and so forth.

-tracecommand cmdPrefix

The option's value should be a command prefix taking four -arguments:

a subject,
a hook,
a list of the hook's argument values, and
a list of objects the hook was called for.

The command will be called for each hook that is called. This allows -the application to trace hook execution for debugging purposes.

Example

The ::model module calls the <Update> hook in response to -commands that change the model's data:

-     hook call ::model <Update>
-

The .view megawidget displays the model state, and needs to -know about model updates. Consequently, it subscribes to the ::model's -<Update> hook.

-     hook bind ::model <Update> .view [list .view ModelUpdate]
-

When the ::model calls the hook, the .views -ModelUpdate subcommand will be called.

Later the .view megawidget is destroyed. In its destructor, -it tells the hook that it no longer exists:

-     hook forget .view
-

All bindings involving .view are deleted.

Credits

Hook has been designed and implemented by William H. Duquette.

Bugs, Ideas, Feedback

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

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

Keywords

callback, event, hook, observer, producer, publisher, subject, subscriber, uevent

Category

Programming tools

Copyright

DELETED embedded/www/tcllib/files/modules/html/html.html Index: embedded/www/tcllib/files/modules/html/html.html ================================================================== --- embedded/www/tcllib/files/modules/html/html.html +++ /dev/null @@ -1,512 +0,0 @@ - -

- -

html(n) 1.4.4 tcllib "HTML Generation"

Name

html - Procedures to generate HTML structures

Table Of Contents
Synopsis
Description
Bugs, Ideas, Feedback
See Also
Keywords
Category

Synopsis

package require Tcl 8.2
package require html ?1.4.4?

::html::author author
::html::bodyTag args
::html::cell param value ?tag?
::html::checkbox name value
::html::checkSet key sep list
::html::checkValue name ?value?
::html::closeTag
::html::default key ?param?
::html::description description
::html::end
::html::eval arg ?args?
::html::extractParam param key ?varName?
::html::font args
::html::for start test next body
::html::foreach varlist1 list1 ?varlist2 list2 ...? body
::html::formValue name ?defvalue?
::html::getFormInfo args
::html::getTitle
::html::h level string ?param?
::html::h1 string ?param?
::html::h2 string ?param?
::html::h3 string ?param?
::html::h4 string ?param?
::html::h5 string ?param?
::html::h6 string ?param?
::html::hdrRow args
::html::head title
::html::headTag string
::html::html_entities string
::html::if expr1 body1 ?elseif expr2 body2 ...? ?else bodyN?
::html::init ?list?
::html::keywords args
::html::mailto email ?subject?
::html::meta args
::html::css href
::html::css-clear
::html::js href
::html::js-clear
::html::minorList list ?ordered?
::html::minorMenu list ?sep?
::html::nl2br string
::html::openTag tag ?param?
::html::paramRow list ?rparam? ?cparam?
::html::passwordInput ?name?
::html::passwordInputRow label ?name?
::html::quoteFormValue value
::html::radioSet key sep list
::html::radioValue name value
::html::refresh seconds url
::html::row args
::html::select name param choices ?current?
::html::selectPlain name param choices ?current?
::html::set var val
::html::submit label ?name?
::html::tableFromArray arrname ?param? ?pat?
::html::tableFromList querylist ?param?
::html::textarea name ?param? ?current?
::html::textInput name value args
::html::textInputRow label name value args
::html::varEmpty name
::html::while test body
::html::doctype id

Description

The package html provides commands that generate HTML. -These commands typically return an HTML string as their result. In -particular, they do not output their result to stdout.

The command ::html::init should be called early to initialize -the module. You can also use this procedure to define default values -for HTML tag parameters.

::html::author author

Side effect only. Call this before ::html::head to -define an author for the page. The author is noted in a comment in -the HEAD section.

::html::bodyTag args

Generate a body tag. The tag parameters are taken from args or -from the body.* attributes define with ::html::init.

::html::cell param value ?tag?

Generate a td (or th) tag, a value, and a closing -td (or th) tag. The -tag parameters come from param or TD.* attributes defined with -::html::init. This uses ::html::font to insert a standard -font tag into the table cell. The tag argument defaults to "td".

::html::checkbox name value

Generate a checkbox form element with the specified name and value. -This uses ::html::checkValue.

::html::checkSet key sep list

Generate a set of checkbox form elements and associated labels. The -list should contain an alternating list of labels and values. -This uses ::html::checkbox. All the checkbox buttons share the -same key for their name. The sep is text used to separate -the elements.

::html::checkValue name ?value?

Generate the "name=name value=value" for a checkbox form -element. If the CGI variable name has the value value, -then SELECTED is added to the return value. value defaults to -"1".

::html::closeTag

Pop a tag off the stack created by ::html::openTag and generate -the corresponding close tag (e.g., </body>).

::html::default key ?param?

This procedure is used by ::html::tagParam to generate the name, -value list of parameters for a tag. The ::html::default -procedure is used to generate default values for those items not -already in param. If the value identified by key matches -a value in param then this procedure returns the empty string. -Otherwise, it returns a "parameter=value" string for a form element -identified by key. The key has the form "tag.parameter" -(e.g., body.bgcolor). Use ::html::init to register default -values. param defaults to the empty string.

::html::description description

Side effect only. Call this before ::html::head to -define a description meta tag for the page. This tag is generated -later in the call to ::html::head.

::html::end

Pop all open tags from the stack and generate the corresponding close -HTML tags, (e.g., </body></html>).

::html::eval arg ?args?

This procedure is similar to the built-in Tcl eval command. The -only difference is that it returns "" so it can be called from an HTML -template file without appending unwanted results.

::html::extractParam param key ?varName?

This is a parsing procedure that extracts the value of key from -param, which is a HTML-style "name=quotedvalue" list. -varName is used as the name of a Tcl variable that is changed to -have the value found in the parameters. The function returns 1 if the -parameter was found in param, otherwise it returns 0. If the -varName is not specified, then key is used as the variable -name.

::html::font args

Generate a standard font tag. The parameters to the tag are taken -from args and the HTML defaults defined with ::html::init.

::html::for start test next body

This procedure is similar to the built-in Tcl for control -structure. Rather than evaluating the body, it returns the subst'ed -body. Each iteration of the loop causes another string to be -concatenated to the result value.

::html::foreach varlist1 list1 ?varlist2 list2 ...? body

This procedure is similar to the built-in Tcl foreach control -structure. Rather than evaluating the body, it returns the subst'ed -body. Each iteration of the loop causes another string to be -concatenated to the result value.

::html::formValue name ?defvalue?

Return a name and value pair, where the value is initialized from -existing CGI data, if any. The result has this form:

-  name="fred" value="freds value"
-

::html::getFormInfo args

Generate hidden fields to capture form values. If args is -empty, then hidden fields are generated for all CGI values. Otherwise -args is a list of string match patterns for form element names.

::html::getTitle

Return the title string, with out the surrounding title tag, -set with a previous call to ::html::title.

::html::h level string ?param?

Generate a heading (e.g., hlevel) tag. The string is nested in the -heading, and param is used for the tag parameters.

::html::h1 string ?param?

Generate an h1 tag. See ::html::h.

::html::h2 string ?param?

Generate an h2 tag. See ::html::h.

::html::h3 string ?param?

Generate an h3 tag. See ::html::h.

::html::h4 string ?param?

Generate an h4 tag. See ::html::h.

::html::h5 string ?param?

Generate an h5 tag. See ::html::h.

::html::h6 string ?param?

Generate an h6 tag. See ::html::h.

::html::hdrRow args

Generate a table row, including tr and th tags. -Each value in args is place into its own table cell. -This uses ::html::cell.

::html::head title

Generate the head section that includes the page title. -If previous calls have been made to -::html::author, -::html::keywords, -::html::description, -or -::html::meta -then additional tags are inserted into the head section. -This leaves an open html tag pushed on the stack with -::html::openTag.

::html::headTag string

Save a tag for inclusion in the head section generated by -::html::head. The string is everything in the tag except -the enclosing angle brackets, < >.

::html::html_entities string

This command replaces all special characters in the string with -their HTML entities and returns the modified text.

::html::if expr1 body1 ?elseif expr2 body2 ...? ?else bodyN?

This procedure is similar to the built-in Tcl if control -structure. Rather than evaluating the body of the branch that is -taken, it returns the subst'ed body. Note that the syntax is -slightly more restrictive than that of the built-in Tcl if -control structure.

::html::init ?list?

::html::init accepts a Tcl-style name-value list that defines -values for items with a name of the form "tag.parameter". For -example, a default with key "body.bgcolor" defines the background -color for the body tag.

::html::keywords args

Side effect only. Call this before ::html::head to -define a keyword meta tag for the page. The meta tag -is included in the result of ::html::head.

::html::mailto email ?subject?

Generate a hypertext link to a mailto: URL.

::html::meta args

Side effect only. Call this before ::html::head to -define a meta tag for the page. The args is a Tcl-style name, -value list that is used for the name= and value= parameters for the -meta tag. The meta tag is included in the result of -::html::head.

::html::css href

Side effect only. Call this before ::html::head to -define a link tag for a linked CSS document. The href -value is a HTTP URL to a CSS document. The link tag is included -in the result of ::html::head.

Multiple calls of this command are allowed, enabling the use of -multiple CSS document references. In other words, the arguments -of multiple calls are accumulated, and do not overwrite each other.

::html::css-clear

Side effect only. Call this before ::html::head to -clear all links to CSS documents.

Multiple calls of this command are allowed, doing nothing after the -first of a sequence with no intervening ::html::css.

::html::js href

Side effect only. Call this before ::html::head to -define a script tag for a linked JavaScript document. The -href is a HTTP URL to a JavaScript document. The script -tag is included in the result of ::html::head.

Multiple calls of this command are allowed, enabling the use of -multiple JavaScript document references. In other words, the arguments -of multiple calls are accumulated, and do not overwrite each other.

::html::js-clear

Side effect only. Call this before ::html::head to -clear all links to JavaScript documents.

Multiple calls of this command are allowed, doing nothing after the -first of a sequence with no intervening ::html::js.

::html::minorList list ?ordered?

Generate an ordered or unordered list of links. The list is a -Tcl-style name, value list of labels and urls for the links. -ordered is a boolean used to choose between an ordered or -unordered list. It defaults to false.

::html::minorMenu list ?sep?

Generate a series of hypertext links. The list is a Tcl-style -name, value list of labels and urls for the links. The sep is -the text to put between each link. It defaults to " | ".

::html::nl2br string

This command replaces all line-endings in the string with a -br tag and returns the modified text.

::html::openTag tag ?param?

Push tag onto a stack and generate the opening tag for -tag. Use ::html::closeTag to pop the tag from the -stack. The second argument provides any tag arguments, as a -list whose elements are formatted to be in the form -"key=value".

::html::paramRow list ?rparam? ?cparam?

Generate a table row, including tr and td tags. Each value in -list is placed into its own table cell. This uses -::html::cell. The value of rparam is used as parameter for -the tr tag. The value of cparam is passed to ::html::cell -as parameter for the td tags.

::html::passwordInput ?name?

Generate an input tag of type password. The name defaults to -"password".

::html::passwordInputRow label ?name?

Format a table row containing a label and an input tag of type -password. The name defaults to "password".

::html::quoteFormValue value

Quote special characters in value by replacing them with HTML -entities for quotes, ampersand, and angle brackets.

::html::radioSet key sep list

Generate a set of input tags of type radio and an associated text -label. All the radio buttons share the same key for their name. -The sep is text used to separate the elements. The list -is a Tcl-style label, value list.

::html::radioValue name value

Generate the "name=name value=value" for a radio form -element. If the CGI variable name has the value value, -then SELECTED is added to the return value.

::html::refresh seconds url

Set up a refresh meta tag. Call this before ::html::head and the -HEAD section will contain a meta tag that causes the document to -refresh in seconds seconds. The url is optional. If -specified, it specifies a new page to load after the refresh interval.

::html::row args

Generate a table row, including tr and td tags. Each value in -args is place into its own table cell. This uses -::html::cell. Ignores any default information set up via -::html::init.

::html::select name param choices ?current?

Generate a select form element and nested option tags. The name -and param are used to generate the select tag. The choices -list is a Tcl-style name, value list.

::html::selectPlain name param choices ?current?

Like ::html::select except that choices is a Tcl list of -values used for the option tags. The label and the value for each -option are the same.

::html::set var val

This procedure is similar to the built-in Tcl set command. The -main difference is that it returns "" so it can be called from an HTML -template file without appending unwanted results. The other -difference is that it must take two arguments.

::html::submit label ?name?

Generate an input tag of type submit. name defaults to "submit".

::html::tableFromArray arrname ?param? ?pat?

Generate a two-column table and nested rows to display a Tcl array. The -table gets a heading that matches the array name, and each generated row -contains a name, value pair. The array names are sorted (lsort without -special options). The argument param is for the table tag and has -to contain a pre-formatted string. The pat is a string match -pattern used to select the array elements to show in the table. It defaults to -*, i.e. the whole array is shown.

::html::tableFromList querylist ?param?

Generate a two-column table and nested rows to display querylist, -which is a Tcl dictionary. Each generated row contains a name, value pair. The -information is shown in the same order as specified in the dictionary. The -argument param is for the table tag and has to contain a -pre-formatted string.

::html::textarea name ?param? ?current?

Generate a textarea tag wrapped around its current values.

::html::textInput name value args

Generate an input form tag with type text. This uses -::html::formValue. The args is any additional tag attributes -you want to put into the input tag.

::html::textInputRow label name value args

Generate an input form tag with type text formatted into a table row -with an associated label. The args is any additional tag attributes -you want to put into the input tag.

::html::varEmpty name

This returns 1 if the named variable either does not exist or has the -empty string for its value.

::html::while test body

This procedure is similar to the built-in Tcl while control -structure. Rather than evaluating the body, it returns the subst'ed -body. Each iteration of the loop causes another string to be -concatenated to the result value.

::html::doctype id

This procedure can be used to build the standard DOCTYPE -declaration string. It will return the standard declaration -string for the id, or throw an error if the id is not known. -The following id's are defined:

HTML32
HTML40
HTML40T
HTML40F
HTML401
HTML401T
HTML401F
XHTML10S
XHTML10T
XHTML10F
XHTML11
XHTMLB

Bugs, Ideas, Feedback

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

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

Keywords

checkbox, checkbutton, form, html, radiobutton, table

Category

CGI programming

DELETED embedded/www/tcllib/files/modules/htmlparse/htmlparse.html Index: embedded/www/tcllib/files/modules/htmlparse/htmlparse.html ================================================================== --- embedded/www/tcllib/files/modules/htmlparse/htmlparse.html +++ /dev/null @@ -1,320 +0,0 @@ - -

- -

htmlparse(n) 1.2.2 tcllib "HTML Parser"

Name

htmlparse - Procedures to parse HTML strings

Table Of Contents
Synopsis
Description
Bugs, Ideas, Feedback
See Also
Keywords
Category

Synopsis

package require Tcl 8.2
package require struct::stack 1.3
package require cmdline 1.1
package require htmlparse ?1.2.2?

::htmlparse::parse ?-cmd cmd? ?-vroot tag? ?-split n? ?-incvar var? ?-queue q? html
::htmlparse::debugCallback ?clientdata? tag slash param textBehindTheTag
::htmlparse::mapEscapes html
::htmlparse::2tree html tree
::htmlparse::removeVisualFluff tree
::htmlparse::removeFormDefs tree

Description

The htmlparse package provides commands that allow libraries -and applications to parse HTML in a string into a representation of -their choice.

The following commands are available:

::htmlparse::parse ?-cmd cmd? ?-vroot tag? ?-split n? ?-incvar var? ?-queue q? html

This command is the basic parser for HTML. It takes an HTML string, -parses it and invokes a command prefix for every tag encountered. It -is not necessary for the HTML to be valid for this parser to -function. It is the responsibility of the command invoked for every -tag to check this. Another responsibility of the invoked command is -the handling of tag attributes and character entities (escaped -characters). The parser provides the un-interpreted tag attributes to -the invoked command to aid in the former, and the package at large -provides a helper command, ::htmlparse::mapEscapes, to aid in -the handling of the latter. The parser does ignore leading -DOCTYPE declarations and all valid HTML comments it encounters.

All information beyond the HTML string itself is specified via -options, these are explained below.

To help understand the options, some more background information about -the parser.

It is capable of detecting incomplete tags in the HTML string given to -it. Under normal circumstances this will cause the parser to throw an -error, but if the option -incvar is used to specify a global (or -namespace) variable, the parser will store the incomplete part of the -input into this variable instead. This will aid greatly in the -handling of incrementally arriving HTML, as the parser will handle -whatever it can and defer the handling of the incomplete part until -more data has arrived.

Another feature of the parser are its two possible modes of -operation. The normal mode is activated if the option -queue is -not present on the command line invoking the parser. If it is present, -the parser will go into the incremental mode instead.

The main difference is that a parser in normal mode will immediately -invoke the command prefix for each tag it encounters. In incremental -mode however the parser will generate a number of scripts which invoke -the command prefix for groups of tags in the HTML string and then -store these scripts in the specified queue. It is then the -responsibility of the caller of the parser to ensure the execution of -the scripts in the queue.

Note: The queue object given to the parser has to provide the -same interface as the queue defined in tcllib -> struct. This means, -for example, that all queues created via that tcllib module can be -immediately used here. Still, the queue doesn't have to come from -tcllib -> struct as long as the same interface is provided.

In both modes the parser will return an empty string to the caller.

The -split option may be given to a parser in incremental mode to -specify the size of the groups it creates. In other words, -split 5 -means that each of the generated scripts will invoke the command -prefix for 5 consecutive tags in the HTML string. A parser in normal -mode will ignore this option and its value.

The option -vroot specifies a virtual root tag. A parser in -normal mode will invoke the command prefix for it immediately before -and after it processes the tags in the HTML, thus simulating that the -HTML string is enclosed in a <vroot> </vroot> combination. In -incremental mode however the parser is unable to provide the closing -virtual root as it never knows when the input is complete. In this -case the first script generated by each invocation of the parser will -contain an invocation of the command prefix for the virtual root as -its first command. -The following options are available:

-cmd cmd: The command prefix to invoke for every tag in the HTML -string. Defaults to ::htmlparse::debugCallback.
-vroot tag: The virtual root tag to add around the HTML in normal mode. In -incremental mode it is the first tag in each chunk processed by the -parser, but there will be no closing tags. Defaults to -hmstart.
-split n: The size of the groups produced by an incremental mode parser. Ignored -when in normal mode. Defaults to 10. Values <= 0 are not allowed.
-incvar var: The name of the variable where to store any incomplete HTML into. This -makes most sense for the incremental mode. The parser will throw an -error if it sees incomplete HTML and has no place to store it to. This -makes sense for the normal mode. Only incomplete tags are detected, -not missing tags. Optional, defaults to 'no variable'.

Interface to the command prefix

In normal mode the parser will invoke the command prefix with four -arguments appended. See ::htmlparse::debugCallback for a -description.

In incremental mode, however, the generated scripts will invoke the -command prefix with five arguments appended. The last four of these -are the same which were mentioned above. The first is a placeholder -string (@win@) for a clientdata value to be supplied later -during the actual execution of the generated scripts. This could be a -tk window path, for example. This allows the user of this package to -preprocess HTML strings without committing them to a specific window, -object, whatever during parsing. This connection can be made -later. This also means that it is possible to cache preprocessed -HTML. Of course, nothing prevents the user of the parser from -replacing the placeholder with an empty string.

::htmlparse::debugCallback ?clientdata? tag slash param textBehindTheTag

This command is the standard callback used by the parser in -::htmlparse::parse if none was specified by the user. It simply -dumps its arguments to stdout. This callback can be used for both -normal and incremental mode of the calling parser. In other words, it -accepts four or five arguments. The last four arguments are described -below. The optional fifth argument contains the clientdata value -passed to the callback by a parser in incremental mode. All callbacks -have to follow the signature of this command in the last four -arguments, and callbacks used in incremental parsing have to follow -this signature in the last five arguments.

The first argument, clientdata, is optional and present only if -this command is invoked by a parser in incremental mode. It contains -whatever the user of this package wishes.

The second argument, tag, contains the name of the tag which is -currently processed by the parser.

The third argument, slash, is either empty or contains a slash -character. It allows the callback to distinguish between opening -(slash is empty) and closing tags (slash contains a slash character).

The fourth argument, param, contains the un-interpreted list of -parameters to the tag.

The fifth and last argument, textBehindTheTag, contains the text -found by the parser behind the tag named in tag.

::htmlparse::mapEscapes html

This command takes a HTML string, substitutes all escape sequences -with their actual characters and then returns the resulting string. -HTML strings which do not contain escape sequences are returned -unchanged.

::htmlparse::2tree html tree

This command is a wrapper around ::htmlparse::parse which takes -an HTML string (in html) and converts it into a tree containing -the logical structure of the parsed document. The name of the tree is -given to the command as its second argument (tree). The command -does not generate the tree by itself but expects that the caller -provided it with an existing and empty tree. It also expects that the -specified tree object follows the same interface as the tree object in -tcllib -> struct. It doesn't have to be from tcllib -> struct, but it -must provide the same interface.

The internal callback does some basic checking of HTML validity and -tries to recover from the most basic errors. The command returns the -contents of its second argument. Side effects are the creation and -manipulation of a tree object.

Each node in the generated tree represent one tag in the input. The -name of the tag is stored in the attribute type of the -node. Any html attributes coming with the tag are stored unmodified in -the attribute data of the tag. In other words, the command does -not parse html attributes into their names and values.

If a tag contains text its node will have children of type -PCDATA containing this text. The text will be stored in the -attribute data of these children.

::htmlparse::removeVisualFluff tree

This command walks a tree as generated by ::htmlparse::2tree and -removes all the nodes which represent visual tags and not structural -ones. The purpose of the command is to make the tree easier to -navigate without getting bogged down in visual information not -relevant to the search. Its only argument is the name of the tree to -cut down.

::htmlparse::removeFormDefs tree

Like ::htmlparse::removeVisualFluff this command is here to cut -down on the size of the tree as generated by -::htmlparse::2tree. It removes all nodes representing forms and -form elements. Its only argument is the name of the tree to cut down.

Bugs, Ideas, Feedback

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

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

Keywords

html, parsing, queue, tree

Category

Text processing

DELETED embedded/www/tcllib/files/modules/http/autoproxy.html Index: embedded/www/tcllib/files/modules/http/autoproxy.html ================================================================== --- embedded/www/tcllib/files/modules/http/autoproxy.html +++ /dev/null @@ -1,344 +0,0 @@ - -

- -

autoproxy(n) 1.7 tcllib "HTTP protocol helper modules"

Name

autoproxy - Automatic HTTP proxy usage and authentication

Table Of Contents
Synopsis
Description
TLS Security Considerations
COMMANDS
OPTIONS
Basic Authentication
EXAMPLES
REFERENCES
BUGS
AUTHORS
Bugs, Ideas, Feedback
See Also
Keywords
Category

Synopsis

package require Tcl 8.5
package require http ?2.0?
package require autoproxy ?1.7?

::autoproxy::init
::autoproxy::cget -option
::autoproxy::configure ?-option value?
::autoproxy::tls_connect args
::autoproxy::tunnel_connect args
::autoproxy::tls_socket args

Description

This package attempts to automate the use of HTTP proxy servers in Tcl -HTTP client code. It tries to initialize the web access settings from -system standard locations and can be configured to negotiate -authentication with the proxy if required.

On Unix the standard for identifying the local HTTP proxy server -seems to be to use the environment variable http_proxy or ftp_proxy and -no_proxy to list those domains to be excluded from proxying. -On Windows we can retrieve the Internet Settings values from the registry -to obtain pretty much the same information. -With this information we can setup a suitable filter procedure for the -Tcl http package and arrange for automatic use of the proxy.

There seem to be a number of ways that the http_proxy environment -variable may be set up. Either a plain host:port or more commonly a -URL and sometimes the URL may contain authentication parameters or -these may be requested from the user or provided via http_proxy_user -and http_proxy_pass. This package attempts to deal with all these -schemes. It will do it's best to get the required parameters from the -environment or registry and if it fails can be reconfigured.

TLS Security Considerations

Note This section only applies if TLS support is provided -by the TLS package. -It does not apply when autoproxy was configured to use some -other package which can provide the same (i.e twapi), via -the -tls_package configuration option.

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

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

COMMANDS

::autoproxy::init

Initialize the autoproxy package from system resources. Under unix -this means we look for environment variables. Under windows we look -for the same environment variables but also look at the registry -settings used by Internet Explorer.

::autoproxy::cget -option

Retrieve individual package configuration options. See OPTIONS.

::autoproxy::configure ?-option value?

Configure the autoproxy package. Calling configure with no -options will return a list of all option names and values. -See OPTIONS.

::autoproxy::tls_connect args

Connect to a secure socket through a proxy. HTTP proxy servers permit -the use of the CONNECT HTTP command to open a link through the proxy -to the target machine. This function hides the details. For use with -the http package see tls_socket.

The args list may contain any of the options -supported by the specific TLS package that is in use but -must end with the host and port as the last two items.

::autoproxy::tunnel_connect args

Connect to a target host throught a proxy. This uses the same CONNECT -HTTP command as the tls_connect but does not promote the link -security once the connection is established.

The args list may contain any of the options -supported by the specific TLS package that is in use but -must end with the host and port as the last two items.

Note that many proxy servers will permit CONNECT calls to a limited -set of ports - typically only port 443 (the secure HTTP port).

::autoproxy::tls_socket args

This function is to be used to register a proxy-aware secure socket -handler for the https protocol. It may only be used with the Tcl http -package and should be registered using the http::register command (see -the examples below). The job of actually creating the tunnelled -connection is done by the tls_connect command and this may be used -when not registering with the http package.

OPTIONS

-host hostname
-proxy_host hostname: Set the proxy hostname. This is normally set up by init but may -be configured here as well.
-port number
-proxy_port number: Set the proxy port number. This is normally set up by init. -e.g. configure -port 3128
-no_proxy list: You may manipulate the no_proxy list that was setup by -init. The value of this option is a tcl list of -strings that are matched against the http request host using the tcl -string match command. Therefore glob patterns are permitted. -For instance, configure -no_proxy *.localdomain
-authProc procedure: This option may be used to set an application defined procedure to be -called when configure -basic is called with either no or -insufficient authentication details. This can be used to present a -dialog to the user to request the additional information.
-basic: Following options are for configuring the Basic authentication -scheme parameters. See Basic Authentication. -To unset the proxy authentication information retained from a previous -call of this function either "--" or no additional parameters can be -supplied. This will remove the existing authentication information.
-tls_package packagename: This option may be used to configure the Tcl package to use for -TLS support. Valid package names are tls (default) -and twapi.

Basic Authentication

Basic is the simplest and most commonly use HTTP proxy authentication -scheme. It is described in (1 section 11) and also in (2). It offers -no privacy whatsoever and its use should be discouraged in favour of -more secure alternatives like Digest. To perform Basic authentication -the client base64 encodes the username and plaintext password -separated by a colon. This encoded text is prefixed with the word -"Basic" and a space.

The following options exists for this scheme:

-username name: The username required to authenticate with the configured proxy.
-password password: The password required for the username specified.
-realm realm: This option is not used by this package but may be used in requesting -authentication details from the user.
--: The end-of-options indicator may be used alone to unset any -authentication details currently enabled.

EXAMPLES

-package require autoproxy
-autoproxy::init
-autoproxy::configure -basic -username ME -password SEKRET
-set tok [http::geturl http://wiki.tcl.tk/]
-http::data $tok
-

-package require http
-package require tls
-package require autoproxy
-autoproxy::init
-http::register https 443 autoproxy::tls_socket
-set tok [http::geturl https://www.example.com/]
-

REFERENCES

Berners-Lee, T., Fielding R. and Frystyk, H. - "Hypertext Transfer Protocol -- HTTP/1.0", - RFC 1945, May 1996, - (http://www.rfc-editor.org/rfc/rfc1945.txt)
Franks, J. et al. - "HTTP Authentication: Basic and Digest Access Authentication", - RFC 2617, June 1999 - (http://www.rfc-editor.org/rfc/rfc2617.txt)

BUGS

At this time only Basic authentication (1) (2) is supported. It is -planned to add support for Digest (2) and NTLM in the future.

AUTHORS

Pat Thoyts

Bugs, Ideas, Feedback

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

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

Keywords

authentication, http, proxy

Category

Networking

DELETED embedded/www/tcllib/files/modules/httpd/httpd.html Index: embedded/www/tcllib/files/modules/httpd/httpd.html ================================================================== --- embedded/www/tcllib/files/modules/httpd/httpd.html +++ /dev/null @@ -1,584 +0,0 @@ - -

- -

tool(n) 4.1.1 tcllib "Tcl Web Server"

Name

tool - A TclOO and coroutine based web server

- -

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 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??
method add_uri pattern dict
method connect sock ip port
method Connect uuid sock ip
method counter which
method CheckTimeout
method dispatch header_dict
method log args
method port_listening
method PrefixNormalize prefix
method start
method stop
method template page
method TemplateSearch page
method Validate_Connection sock ip
method ENSEMBLE::add field element
method ENSEMBLE::dump
method ENSEMBLE::get field
method ENSEMBLE::reset
method ENSEMBLE::remove field element
method ENSEMBLE::replace keyvaluelist
method ENSEMBLE::reset
method ENSEMBLE::set field value
method http_info::netstring
method request::parse string
method reply::output
method close
method HttpHeaders sock ?debug?
method dispatch newsock datastate
method error code ?message? ?errorInfo?
method content
method EncodeStatus status
method FormData
method MimeParse mimetext
method DoOutput
method PostData length
method puts string
method reset
method timeOutCheck
method timestamp
method TransferComplete args
method Url_Decode string
method cgi_info
option path
option prefix
method proxy_info
method scgi_info

Description

This module implements a web server, suitable for embedding in an -application. The server is object oriented, and contains all of the -fundamentals needed for a full service website.

Minimal Example

Starting a web service requires starting a class of type -httpd::server, and providing that server with one or more URIs -to service, and httpd::reply derived classes to generate them.

-tool::define ::reply.hello {
-  method content {} {
-    my puts "<HTML><HEAD><TITLE>IRM Dispatch Server</TITLE></HEAD><BODY>"
-    my puts "<h1>Hello World!</h1>"
-    my puts </BODY></HTML>
-  }
-}
-::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 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 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

A class which shephards a request through the process of generating a -reply. -The socket associated with the reply is available at all times as the chan -variable. -The process of generating a reply begins with an httpd::server generating a -http::class object, mixing in a set of behaviors and then invoking the reply -object's dispatch method. -In normal operations the dispatch method:

Invokes the reset method for the object to populate default headers.
Invokes the HttpHeaders method to stream the MIME headers out of the socket
Invokes the request parse method to convert the stream of MIME headers into a -dict that can be read via the request method.
Stores the raw stream of MIME headers in the rawrequest variable of the object.
Invokes the content method for the object, generating an call to the error -method if an exception is raised.
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 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 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 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 {} {
-	  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 "<BODY>"
-    my puts "You Sent<p>"
-    my puts "<TABLE>"
-    foreach {f v} $form {
-      my puts "<TR><TH>$f</TH><TD><verbatim>$v</verbatim></TD>"
-    }
-    my puts "</TABLE><p>"
-    my puts "Send some info:<p>"
-    my puts "<FORM action=/[my http_info get REQUEST_PATH] method POST>"
-    my puts "<TABLE>"
-    foreach field {name rank serial_number} {
-      set line "<TR><TH>$field</TH><TD><input name=\"$field\" "
-      if {[dict exists $form $field]} {
-        append line " value=\"[dict get $form $field]\"""
-      }
-      append line " /></TD></TR>"
-      my puts $line
-    }
-    my puts "</TABLE>"
-    my puts [my html footer]
-	}
-}
-

method EncodeStatus status

Formulate a standard HTTP status header from he string provided.

method FormData

For GET requests, converts the QUERY_DATA header into a key/value list. -For POST requests, reads the Post data and converts that information to -a key/value list for application/x-www-form-urlencoded posts. For multipart -posts, it composites all of the MIME headers of the post to a singular key/value -list, and provides MIME_* information as computed by the mime package, including -the MIME_TOKEN, which can be fed back into the mime package to read out the contents.

method MimeParse mimetext

Converts a block of mime encoded text to a key/value list. If an exception is encountered, -the method will generate its own call to the error method, and immediately invoke -the output method to produce an error code and close the connection.

method DoOutput

Generates the the HTTP reply, and streams that reply back across chan.

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

Appends the value of string to the end of reply_body, as well as a trailing newline -character.

method reset

Clear the contents of the reply_body variable, and reset all headers in the reply -structure back to the defaults for this object.

method timeOutCheck

Called from the http::server object which spawned this reply. Checks to see -if too much time has elapsed while waiting for data or generating a reply, and issues -a timeout error to the request if it has, as well as destroy the object and close the -chan socket.

method timestamp

Return the current system time in the format:

%a, %d %b %Y %T %Z

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

Sean Woods

Bugs, Ideas, Feedback

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

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

Keywords

TclOO, WWW, http, httpd, httpserver, services

Category

Networking

Copyright

DELETED embedded/www/tcllib/files/modules/ident/ident.html Index: embedded/www/tcllib/files/modules/ident/ident.html ================================================================== --- embedded/www/tcllib/files/modules/ident/ident.html +++ /dev/null @@ -1,179 +0,0 @@ - -

- -

ident(n) 0.42 tcllib "Identification protocol client"

Name

ident - Ident protocol client

Table Of Contents
Synopsis
Description
Bugs, Ideas, Feedback
Keywords
Category
Copyright

Synopsis

Description

The ident package provides a client implementation of the ident -protocol as defined in -RFC 1413 (http://www.rfc-editor.org/rfc/rfc1413.txt).

::ident::query socket ?callback?

Bugs, Ideas, Feedback

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

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

Keywords

ident, identification, rfc 1413

Category

Networking

Copyright

DELETED embedded/www/tcllib/files/modules/imap4/imap4.html Index: embedded/www/tcllib/files/modules/imap4/imap4.html ================================================================== --- embedded/www/tcllib/files/modules/imap4/imap4.html +++ /dev/null @@ -1,487 +0,0 @@ -

- -

imap4(n) 0.5.3 tcllib "imap client"

DELETED embedded/www/tcllib/files/modules/inifile/ini.html Index: embedded/www/tcllib/files/modules/inifile/ini.html ================================================================== --- embedded/www/tcllib/files/modules/inifile/ini.html +++ /dev/null @@ -1,210 +0,0 @@ - -

- -

[ - -| -| -| -| -| - ]

DELETED embedded/www/tcllib/files/modules/interp/deleg_method.html Index: embedded/www/tcllib/files/modules/interp/deleg_method.html ================================================================== --- embedded/www/tcllib/files/modules/interp/deleg_method.html +++ /dev/null @@ -1,174 +0,0 @@ - -

aes	Implementation of the AES block cipher
ascii85	ascii85-encode/decode binary data
asn	ASN.1 BER encoder/decoder
autoproxy	Automatic HTTP proxy usage and authentication
base32	base32 standard encoding
base32::core	Expanding basic base32 maps
base32::hex	base32 extended hex encoding
base64	base64-encode/decode binary data
bee	BitTorrent Serialization Format Encoder/Decoder
bench	bench - Processing benchmark suites
bench::in	bench::in - Reading benchmark results
bench::out::csv	bench::out::csv - Formatting benchmark results as CSV
bench::out::text	bench::out::text - Formatting benchmark results as human readable text
bench_intro	bench introduction
bench_lang_intro	bench language introduction
bench_lang_spec	bench language specification
bibtex	Parse bibtex files
blowfish	Implementation of the Blowfish block cipher
cache::async	Asynchronous in-memory cache
cksum	Calculate a cksum(1) compatible checksum
clock_iso8601	Parsing ISO 8601 dates/times
clock_rfc2822	Parsing ISO 8601 dates/times
cmdline	Procedures to process command lines and options.
comm	A remote communication facility for Tcl (8.3 and later)
comm_wire	The comm wire protocol
control	Procedures for control flow structures.
coroutine	Coroutine based event and IO handling
coroutine::auto	Automatic event and IO coroutine awareness
counter	Procedures for counters and histograms
crc16	Perform a 16bit Cyclic Redundancy Check
crc32	Perform a 32bit Cyclic Redundancy Check
cron	Tool for automating the period callback of commands
csv	Procedures to handle CSV data.
debug	debug narrative - core
debug::caller	debug narrative - caller
debug::heartbeat	debug narrative - heartbeat
debug::timestamp	debug narrative - timestamping
defer	Defered execution
deleg_method	Creation of comm delegates (snit methods)
deleg_proc	Creation of comm delegates (procedures)
des	Implementation of the DES and triple-DES ciphers
dicttool	Dictionary Tools
dns	Tcl Domain Name Service Client
docidx_intro	docidx introduction
docidx_lang_cmdref	docidx language command reference
docidx_lang_faq	docidx language faq
docidx_lang_intro	docidx language introduction
docidx_lang_syntax	docidx language syntax
docidx_plugin_apiref	docidx plugin API reference
docstrip	Docstrip style source code extraction
docstrip_util	Docstrip-related utilities
doctoc_intro	doctoc introduction
doctoc_lang_cmdref	doctoc language command reference
doctoc_lang_faq	doctoc language faq
doctoc_lang_intro	doctoc language introduction
doctoc_lang_syntax	doctoc language syntax
doctoc_plugin_apiref	doctoc plugin API reference
doctools	doctools - Processing documents
doctools2idx_introduction	DocTools - Keyword indices
doctools2toc_introduction	DocTools - Tables of Contents
doctools::changelog	Processing text in Emacs ChangeLog format
doctools::cvs	Processing text in 'cvs log' format
doctools::html::cssdefaults	Default CSS style for HTML export plugins
doctools::idx	docidx - Processing indices
doctools::idx	Holding keyword indices
doctools::idx::export	Exporting keyword indices
doctools::idx::export::docidx	docidx export plugin
doctools::idx::export::html	HTML export plugin
doctools::idx::export::json	JSON export plugin
doctools::idx::export::nroff	nroff export plugin
doctools::idx::export::text	plain text export plugin
doctools::idx::export::wiki	wiki export plugin
doctools::idx::import	Importing keyword indices
doctools::idx::import::docidx	docidx import plugin
doctools::idx::import::json	JSON import plugin
doctools::idx::parse	Parsing text in docidx format
doctools::idx::structure	Docidx serialization utilities
doctools::msgcat	Message catalog management for the various document parsers
doctools::msgcat::idx::c	Message catalog for the docidx parser (C)
doctools::msgcat::idx::de	Message catalog for the docidx parser (DE)
doctools::msgcat::idx::en	Message catalog for the docidx parser (EN)
doctools::msgcat::idx::fr	Message catalog for the docidx parser (FR)
doctools::msgcat::toc::c	Message catalog for the doctoc parser (C)
doctools::msgcat::toc::de	Message catalog for the doctoc parser (DE)
doctools::msgcat::toc::en	Message catalog for the doctoc parser (EN)
doctools::msgcat::toc::fr	Message catalog for the doctoc parser (FR)
doctools::nroff::man_macros	Default CSS style for NROFF export plugins
doctools::tcl::parse	Processing text in 'subst -novariables' format
doctools::toc	Holding tables of contents
doctools::toc	doctoc - Processing tables of contents
doctools::toc::export	Exporting tables of contents
doctools::toc::export::doctoc	doctoc export plugin
doctools::toc::export::html	HTML export plugin
doctools::toc::export::json	JSON export plugin
doctools::toc::export::nroff	nroff export plugin
doctools::toc::export::text	plain text export plugin
doctools::toc::export::wiki	wiki export plugin
doctools::toc::import	Importing keyword indices
doctools::toc::import::doctoc	doctoc import plugin
doctools::toc::import::json	JSON import plugin
doctools::toc::parse	Parsing text in doctoc format
doctools::toc::structure	Doctoc serialization utilities
doctools_intro	doctools introduction
doctools_lang_cmdref	doctools language command reference
doctools_lang_faq	doctools language faq
doctools_lang_intro	doctools language introduction
doctools_lang_syntax	doctools language syntax
doctools_plugin_apiref	doctools plugin API reference
dtplite	Lightweight DocTools Markup Processor
dtplite	Lightweight DocTools Markup Processor
fileutil	Procedures implementing some file utilities
fileutil::magic::cfront	Generator core for compiler of magic(5) files
fileutil::magic::cgen	Generator core for compiler of magic(5) files
fileutil::magic::filetype	Procedures implementing file-type recognition
fileutil::magic::rt	Runtime core for file type recognition engines written in pure Tcl
fileutil::multi	Multi-file operation, scatter/gather, standard object
fileutil::multi::op	Multi-file operation, scatter/gather
fileutil_traverse	Iterative directory traversal
ftp	Client-side tcl implementation of the ftp protocol
ftp::geturl	Uri handler for ftp urls
ftpd	Tcl FTP server implementation
generator	Procedures for creating and using generators.
gpx	Extracts waypoints, tracks and routes from GPX files
grammar::aycock	Aycock-Horspool-Earley parser generator for Tcl
grammar::fa	Create and manipulate finite automatons
grammar::fa::dacceptor	Create and use deterministic acceptors
grammar::fa::dexec	Execute deterministic finite automatons
grammar::fa::op	Operations on finite automatons
grammar::me::cpu	Virtual machine implementation II for parsing token streams
grammar::me::cpu::core	ME virtual machine state manipulation
grammar::me::cpu::gasm	ME assembler
grammar::me::tcl	Virtual machine implementation I for parsing token streams
grammar::me::util	AST utilities
grammar::me_ast	Various representations of ASTs
grammar::me_intro	Introduction to virtual machines for parsing token streams
grammar::me_vm	Virtual machine for parsing token streams
grammar::peg	Create and manipulate parsing expression grammars
grammar::peg::interp	Interpreter for parsing expression grammars
hook	Hooks
html	Procedures to generate HTML structures
htmlparse	Procedures to parse HTML strings
huddle	Create and manipulate huddle object
ident	Ident protocol client
imap4	imap client-side tcl implementation of imap protocol
inifile	Parsing of Windows INI files
interp	Interp creation and aliasing
irc	Create IRC connection and interface.
javascript	Procedures to generate HTML and Java Script structures.
jpeg	JPEG querying and manipulation of meta data
json	JSON parser
json::write	JSON generation
lambda	Utility commands for anonymous procedures
lazyset	Lazy evaluation
ldap	LDAP client
ldapx	LDAP extended object interface
log	Procedures to log messages of libraries and applications.
logger	System to control logging of events.
logger::appender	Collection of predefined appenders for logger
logger::utils	Utilities for logger
map::geocode::nominatim	Resolving geographical names with a Nominatim service
map::slippy	Common code for slippy based map packages
map::slippy::cache	Management of a tile cache in the local filesystem
map::slippy::fetcher	Accessing a server providing tiles for slippy-based maps
mapproj	Map projection routines
markdown	Converts Markdown text to HTML
math	Tcl Math Library
math::bigfloat	Arbitrary precision floating-point numbers
math::bignum	Arbitrary precision integer numbers
math::calculus	Integration and ordinary differential equations
math::calculus::romberg	Romberg integration
math::calculus::symdiff	Symbolic differentiation for Tcl
math::combinatorics	Combinatorial functions in the Tcl Math Library
math::complexnumbers	Straightforward complex number package
math::constants	Mathematical and numerical constants
math::decimal	General decimal arithmetic
math::exact	Exact Real Arithmetic
math::fourier	Discrete and fast fourier transforms
math::fuzzy	Fuzzy comparison of floating-point numbers
math::geometry	Geometrical computations
math::interpolate	Interpolation routines
math::linearalgebra	Linear Algebra
math::numtheory	Number Theory
math::optimize	Optimisation routines
math::PCA	Package for Principal Component Analysis
math::polynomials	Polynomial functions
math::rationalfunctions	Polynomial functions
math::roman	Tools for creating and manipulating roman numerals
math::special	Special mathematical functions
math::statistics	Basic statistical functions and procedures
math::trig	Trigonometric anf hyperbolic functions
md4	MD4 Message-Digest Algorithm
md5	MD5 Message-Digest Algorithm
md5crypt	MD5-based password encryption
mime	Manipulation of MIME body parts
mpexpand	Markup processor
multiplexer	One-to-many communication with sockets.
nameserv	Name service facility, Client
nameserv::auto	Name service facility, Client Extension
nameserv::common	Name service facility, shared definitions
nameserv::protocol	Name service facility, client/server protocol
nameserv::server	Name service facility, Server
namespacex	Namespace utility commands
ncgi	Procedures to manipulate CGI values.
nettool	Tools for networked applications
nmea	Process NMEA data
nns	Name service facility, Commandline Client Application
nns_intro	Name service facility, introduction
nnsd	Name service facility, Commandline Server Application
nnslog	Name service facility, Commandline Logging Client Application
nntp	Tcl client for the NNTP protocol
ntp_time	Tcl Time Service Client
oauth	oauth API base signature
oo::util	Utility commands for TclOO
oo::util	Utility commands for TclOO
oometa	oo::meta A data registry for classess
otp	One-Time Passwords
page	Parser Generator
page_intro	page introduction
page_pluginmgr	page plugin manager
page_util_flow	page dataflow/treewalker utility
page_util_norm_lemon	page AST normalization, LEMON
page_util_norm_peg	page AST normalization, PEG
page_util_peg	page PEG transformation utilities
page_util_quote	page character quoting utilities
picoirc	Small and simple embeddable IRC client.
pki	Implementation of the public key cipher
pluginmgr	Manage a plugin
png	PNG querying and manipulation of meta data
pop3	Tcl client for POP3 email protocol
pop3d	Tcl POP3 server implementation
pop3d::dbox	Simple mailbox database for pop3d
pop3d::udb	Simple user database for pop3d
practcl	The Practcl Module
processman	Tool for automating the period callback of commands
profiler	Tcl source code profiler
pt	Parser Tools Application
pt::ast	Abstract Syntax Tree Serialization
pt::cparam::configuration::critcl	C/PARAM, Canned configuration, Critcl
pt::cparam::configuration::tea	C/PARAM, Canned configuration, TEA
pt::json_language	The JSON Grammar Exchange Format
pt::param	PackRat Machine Specification
pt::pe	Parsing Expression Serialization
pt::pe::op	Parsing Expression Utilities
pt::peg	Parsing Expression Grammar Serialization
pt::peg::container	PEG Storage
pt::peg::container::peg	PEG Storage. Canned PEG grammar specification
pt::peg::export	PEG Export
pt::peg::export::container	PEG Export Plugin. Write CONTAINER format
pt::peg::export::json	PEG Export Plugin. Write JSON format
pt::peg::export::peg	PEG Export Plugin. Write PEG format
pt::peg::from::container	PEG Conversion. From CONTAINER format
pt::peg::from::json	PEG Conversion. Read JSON format
pt::peg::from::peg	PEG Conversion. Read PEG format
pt::peg::import	PEG Import
pt::peg::import::container	PEG Import Plugin. From CONTAINER format
pt::peg::import::json	PEG Import Plugin. Read JSON format
pt::peg::import::peg	PEG Import Plugin. Read PEG format
pt::peg::interp	Interpreter for parsing expression grammars
pt::peg::to::container	PEG Conversion. Write CONTAINER format
pt::peg::to::cparam	PEG Conversion. Write CPARAM format
pt::peg::to::json	PEG Conversion. Write JSON format
pt::peg::to::param	PEG Conversion. Write PARAM format
pt::peg::to::peg	PEG Conversion. Write PEG format
pt::peg::to::tclparam	PEG Conversion. Write TCLPARAM format
pt::peg_language	PEG Language Tutorial
pt::pegrammar	Introduction to Parsing Expression Grammars
pt::pgen	Parser Generator
pt::rde	Parsing Runtime Support, PARAM based
pt::tclparam::configuration::nx	Tcl/PARAM, Canned configuration, NX
pt::tclparam::configuration::snit	Tcl/PARAM, Canned configuration, Snit
pt::tclparam::configuration::tcloo	Tcl/PARAM, Canned configuration, Tcloo
pt::util	General utilities
pt_export_api	Parser Tools Export API
pt_import_api	Parser Tools Import API
pt_introduction	Introduction to Parser Tools
pt_parse_peg	Parser Tools PEG Parser
pt_parser_api	Parser API
pt_peg_op	Parser Tools PE Grammar Utility Operations
rc4	Implementation of the RC4 stream cipher
rcs	RCS low level utilities
report	Create and manipulate report objects
rest	define REST web APIs and call them inline or asychronously
ripemd128	RIPEMD-128 Message-Digest Algorithm
ripemd160	RIPEMD-160 Message-Digest Algorithm
S3	Amazon S3 Web Service Interface
SASL	Implementation of SASL mechanisms for Tcl
SASL::NTLM	Implementation of SASL NTLM mechanism for Tcl
SASL::SCRAM	Implementation of SASL SCRAM mechanism for Tcl
SASL::XGoogleToken	Implementation of SASL NTLM mechanism for Tcl
sha1	SHA1 Message-Digest Algorithm
sha256	SHA256 Message-Digest Algorithm
simulation::annealing	Simulated annealing
simulation::montecarlo	Monte Carlo simulations
simulation::random	Pseudo-random number generators
smtp	Client-side tcl implementation of the smtp protocol
smtpd	Tcl SMTP server implementation
snit	Snit's Not Incr Tcl
snitfaq	Snit Frequently Asked Questions
soundex	Soundex
stooop	Object oriented extension.
string::token	Regex based iterative lexing
string::token::shell	Parsing of shell command line
stringprep	Implementation of stringprep
stringprep::data	stringprep data tables, generated, internal
struct::disjointset	Disjoint set data structure
struct::graph	Create and manipulate directed graph objects
struct::graph::op	Operation for (un)directed graph objects
struct::graph_v1	Create and manipulate directed graph objects
struct::list	Procedures for manipulating lists
struct::matrix	Create and manipulate matrix objects
struct::matrix_v1	Create and manipulate matrix objects
struct::pool	Create and manipulate pool objects (of discrete items)
struct::prioqueue	Create and manipulate prioqueue objects
struct::queue	Create and manipulate queue objects
struct::record	Define and create records (similar to 'C' structures)
struct::set	Procedures for manipulating sets
struct::skiplist	Create and manipulate skiplists
struct::stack	Create and manipulate stack objects
struct::tree	Create and manipulate tree objects
struct::tree_v1	Create and manipulate tree objects
sum	Calculate a sum(1) compatible checksum
switched	switch/option management.
tar	Tar file creation, extraction & manipulation
tcl::chan::cat	Concatenation channel
tcl::chan::core	Basic reflected/virtual channel support
tcl::chan::events	Event support for reflected/virtual channels
tcl::chan::facade	Facade channel
tcl::chan::fifo	In-memory fifo channel
tcl::chan::fifo2	In-memory interconnected fifo channels
tcl::chan::halfpipe	In-memory channel, half of a fifo2
tcl::chan::memchan	In-memory channel
tcl::chan::null	Null channel
tcl::chan::nullzero	Null/Zero channel combination
tcl::chan::random	Random channel
tcl::chan::std	Standard I/O, unification of stdin and stdout
tcl::chan::string	Read-only in-memory channel
tcl::chan::textwindow	Textwindow channel
tcl::chan::variable	In-memory channel using variable for storage
tcl::chan::zero	Zero channel
tcl::randomseed	Utilities for random channels
tcl::transform::adler32	Adler32 transformation
tcl::transform::base64	Base64 encoding transformation
tcl::transform::core	Basic reflected/virtual channel transform support
tcl::transform::counter	Counter transformation
tcl::transform::crc32	Crc32 transformation
tcl::transform::hex	Hexadecimal encoding transformation
tcl::transform::identity	Identity transformation
tcl::transform::limitsize	limiting input
tcl::transform::observe	Observer transformation, stream copy
tcl::transform::otp	Encryption via one-time pad
tcl::transform::rot	rot-encryption
tcl::transform::spacer	Space insertation and removal
tcl::transform::zlib	zlib (de)compression
tclDES	Implementation of the DES and triple-DES ciphers
tclDESjr	Implementation of the DES and triple-DES ciphers
tcldocstrip	Tcl-based Docstrip Processor
tcllib_ip	IPv4 and IPv6 address manipulation
tclrep/machineparameters	Compute double precision machine parameters.
tepam	An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
tepam::argument_dialogbox	TEPAM argument_dialogbox, reference manual
tepam::doc_gen	TEPAM DOC Generation, reference manual
tepam::procedure	TEPAM procedure, reference manual
term	General terminal control
term::ansi::code	Helper for control sequences
term::ansi::code::attr	ANSI attribute sequences
term::ansi::code::ctrl	ANSI control sequences
term::ansi::code::macros	Macro sequences
term::ansi::ctrl::unix	Control operations and queries
term::ansi::send	Output of ANSI control sequences to terminals
term::interact::menu	Terminal widget, menu
term::interact::pager	Terminal widget, paging
term::receive	General input from terminals
term::receive::bind	Keyboard dispatch from terminals
term::send	General output to terminals
textutil	Procedures to manipulate texts and strings.
textutil::adjust	Procedures to adjust, indent, and undent paragraphs
textutil::expander	Procedures to process templates and expand text.
textutil::repeat	Procedures to repeat strings.
textutil::split	Procedures to split texts
textutil::string	Procedures to manipulate texts and strings.
textutil::tabify	Procedures to (un)tabify strings
textutil::trim	Procedures to trim strings
throw	throw - Throw an error exception with a message
tie	Array persistence, standard data sources
tie	Array persistence
tiff	TIFF reading, writing, and querying and manipulation of meta data
tool	A TclOO and coroutine based web server
tool	TclOO Library (TOOL) Framework
tool::dict_ensemble	Dictionary Tools
transfer::connect	Connection setup
transfer::copy	Data transfer foundation
transfer::copy::queue	Queued transfers
transfer::data::destination	Data destination
transfer::data::source	Data source
transfer::receiver	Data source
transfer::transmitter	Data source
treeql	Query tree objects
try	try - Trap and process errors and exceptions
udpcluster	UDP Peer-to-Peer cluster
uevent	User events
uevent::onidle	Request merging and deferal to idle time
unicode	Implementation of Unicode normalization
unicode::data	unicode data tables, generated, internal
units	unit conversion
uri	URI utilities
uri_urn	URI utilities, URN scheme
uuencode	UU-encode/decode binary data
uuid	UUID generation and comparison
valtype::common	Validation, common code
valtype::creditcard::amex	Validation for AMEX creditcard number
valtype::creditcard::discover	Validation for Discover creditcard number
valtype::creditcard::mastercard	Validation for Mastercard creditcard number
valtype::creditcard::visa	Validation for VISA creditcard number
valtype::gs1::ean13	Validation for EAN13
valtype::iban	Validation for IBAN
valtype::imei	Validation for IMEI
valtype::isbn	Validation for ISBN
valtype::luhn	Validation for plain number with a LUHN checkdigit
valtype::luhn5	Validation for plain number with a LUHN5 checkdigit
valtype::usnpi	Validation for USNPI
valtype::verhoeff	Validation for plain number with a VERHOEFF checkdigit
websocket	Tcl implementation of the websocket protocol
wip	Word Interpreter
xsxp	eXtremely Simple Xml Parser
yaml	YAML Format Encoder/Decoder
yencode	Y-encode/decode binary data
zipfile::decode	Access to zip archives
zipfile::encode	Generation of zip archives
zipfile::mkzip	Build a zip archive

Discussion & Contact

Hello World!

tepam::doc_gen

Generate

Patch

Keyword Index

dtplite(n) 1.0.5 tcllib "Documentation toolbox"

nns(n) 1.1 tcllib "Name service facility"

nnsd(n) 1.0.1 tcllib "Name service facility"

nnslog(n) 1.0 tcllib "Name service facility"

page(n) 1.0 tcllib "Development Tools"

pt(n) 1 tcllib "Parser Tools"

tcldocstrip(n) 1.0 tcllib "Textprocessing toolbox"

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

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

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